What is the purpose of (what look like) annotations placed in comments? For example, I'm seeing the following comment above a method in an interface:
/**
* Create saved search
* REST: POST /lifecycles/savedsearches
* #param controlParameters control parameters
* #param search savedSearch object
* #throws ProcessingException if any processing exceptions
* #return Updated Object
*/
I understand the meaning of the comment, just wondering why this syntax was used.
These annotations are important for the javadoc tool. When it generates a documentation for a class/interface/enum/constructor/method if parses the content between /** and */.
For a single piece of javadoc content, the tool generates a HTML-based documentation, which consists of several paragraphs. When it detects an annotation (e.g. #param) it adds the corresponding #param information to the paragraph about the Parameters of a method.
Checkout the String#concat(String str) method, for example.
Also, take a look on the Oracle's Javadoc home page
This is used when generating Javadoc. That way you can add an explanatory text for each parameter passed to the function and you can explain what's returned and what exceptions can be thrown and the Javadoc generator then adds your comments to the methods documentation in its corresponding places.
Then you can use that to generate html pages documenting your code based on these comments.
It's used then for javadoc generation. See http://www.oracle.com/technetwork/articles/java/index-jsp-135444.html
This syntax is used if you generate Javadoc.
http://www.oracle.com/technetwork/articles/java/index-137868.html
Related
Say I have a class, and I renamed it.
How should i change the documentation of the class?
This is what the the javadoc of the class currently looks like
/**
* Single report.
*
* <p>There is no thread-safety guarantee.
*
* #author Yegor Bugayenko (yegor256#gmail.com)
* #version $Id: 532ae3783f6bcb7ffa6819b91ebee78670aa82e3 $
* #since 0.1
* #checkstyle ClassDataAbstractionCouplingCheck (500 lines)
* #checkstyle JavadocTagsCheck (500 lines)
*/
If the change only affects the name of the class, only the name occurrences in documentation, configuration and other references need to be replaced accordingly. As the JavaDoc does not contain any class names, there's nothing to do in that particular place.
IDE's like IntelliJ or Eclipse can help a lot when doing refactorings like that because they offer tools to perform the replace in a safe and convenient way. In simple cases a text editor with search and replace functionality might suffice.
After an automatic replace I'd go through all the changes manually and double check if they had the intended affect as sometimes the context is affected from the change as well and needs to be adapted.
I have a Java class with a generic type P. I want to document it in Javadoc. Normally I just do this:
/**
* ...
* #param <P> the type of publisher
*/
This shows up fine in actual Javadoc. However, CheckStyle is warning me that I need to document the type P because it renders <P> as a HTML paragraph. Also, the Eclipse formatter interprets it as a paragraph as well, so it messes up the formatting.
Is there a better way of documenting type parameters with type P? I know I can disable the Eclipse formatter to no longer auto format javadoc, but I'd rather not (and it wouldn't solve the checkstyle problem anyway).
I also know I can just rename P to something else, but given the number of generic types I am working with here, it would make things a lot less readable.
This is a bug in CheckStyle.
The official Javadoc documentation says that notation is correct:
Example of a type parameter of a class:
/**
* #param <E> Type of element stored in a list
*/
If you're stuck with this version of CheckStyle, then the only way to satisfy both constraints is to rename your P type parameter to something else.
FOR POSTERITY: Turns out Checkstyle handles it just fine. The problem is that the whitespace added by the Eclipse formatter made Checkstyle (reasonably) argue that the Javadoc was incorrect. I also found an existing bug report for this bug in Eclipse: https://bugs.eclipse.org/bugs/show_bug.cgi?id=121728
Just skip "<" and ">" characters. They are not part of the type name; they are part of syntax.
#param P the type of publisher
(Not sure how it works with CheckStyle, but Eclipse should be satisfied.)
We found out that hitting Ctrl+S to save and then Ctrl-Z to undo the formatting will correctly save the Javadoc with an #param <P> tag.
I just wanted to know if there are any differences between these types of comments.
/*
...
Content of the comment
...
*/
and
/*
* ...
* Content of the comment
* ...
*/
No, there is no difference. It's purely a style decision.
No difference, but this syntax
/*
* ...
* Content of the comment
* ...
*/
is more appropriate for generating JavaDoc
From http://javadude.com/articles/comments.html
Documentation comments should (at very least) be used in front of
every public class, interface, method and class/instance variable in
your source code. This allows someone to run javadoc against the code
and generate a simple document that lists the public entities and a
brief description of each. You may also use documentation comments in
front on non-public methods, and use a javadoc option to generate
documentation for them. Using documentation comments on non-public
entities is not as important as publics (the interface isn't
exposed...) but if you're commenting the code anyway you might as well
write those comments as documentation comments.
No it makes no difference.
Side Note (for the sake of completeness)
There is a difference between the following to examples.
/*
* ...
* Content of the comment
* ...
*/
and
/**
* ...
* Content of the comment
* ...
*/
the second one indicates a javadoc comment (the ** at the first line of the comment). There you can use different tags to enhance your javadoc.
There isn't any difference. Just a different way.
I'd prefer the first form:
/*
something
*/
Specially if the commented out part is code and if I am trying something out. For obvious reasons, extra asterixes at the beginning of each line causes head aches for this case.
Modern IDE's also support short-cuts for commenting multiple lines at the same time. For example in Eclipse, you can select a few lines and press CTRL + / to comment them out. The form of comments is though would be as follows:
// line1
// line2
// ...
There is no difference
As a developer What ever the code we are writing we need to make a small document on top of that particular code.for documenting purpose we will use these comments based on our choice we can use what ever we want.
I am developing a library which is used for some specific validation operations. Every thing is ok for me in usage, but when I publish it, every time developers need to read manual document.
So, I want to show usage tips like shown blow.
How can i do it ?
You need to write JavaDoc comments in your code and then you can generate JavaDoc html.
JavaDoc comments are special comments which are between /** and */ and can be used to generate JavaDoc. e.g.
/**
* Class description.
* <p>
* Some more details
*
* #author Edd
*/
public class MyClass {
/**
* Method description.
*
* #param param
* important parameter
*/
public static void myMethod(String param) {
}
}
This would then look like this as a tooltip:
When you release your library for other developers to use, you would typically release it as a jar file. When you package up your jar you should also generate a javadoc.jar file to accompany your jar. This can then be used by other developers to get the usage tips.
Write JavaDoc comments and publish them together with your library.
If you are using Maven, you can use the javadoc:jar goal of the Maven Javadoc Plugin.
Read about and use javadoc, here: http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html
is there a reason i should prefer to write inline-comments in java like this:
/** Init operation */
mindControlLaser.engage();
as opposed to use just one *:
/* i'm a happy comment */
Eclipse colours the syntax differently, but is there really anything in the "toolchain" (javadoc, eclipse, etc.) giving me an advantage when using /** */ ?
No reason for inline comments.
/** signals to javadoc utility to extract documentation about your API automatically. It does not have any effect when is used inside methods.
Regular comments
/* Regular comment */
With regular comments you explain maybe a part of an algorithm that is tricky.
Or anything that you don't want to be a part of the JavaDOC. Inline comments are regular comments too, and can be used for example when the description is shorter.
Java Documentation
/** JAVA DOC COMMENT */
With javadoc you explain classes, methods, or fields(variables).
Then, most IDEs like Eclipse can use this information to help you while you code.
For example, if you have a classA and a classB, and in classB you use stuff from classA, then if you hover on methods or variables you can see the JavaDOC information. It's very handy.
Also, with build tools like ant you can automatically build HTML files out of the JavaDOC, and if you publish them you can allow others to reuse your work.
Look for example the documentation of Java itself here.
The syntax for a comment is /* */.
Javadoc has as a default that you use /** */. This is a comment because the second * is inside the comment, so would not be seen differently by your compiler.
So without a second * you are just adding a comment, and with the second one you write javadoc: eclipse will recognize it and give you hints etc when hovering on the functioncall somewhere else.
/** .... */ will generate Javadoc, /* ... */ won't.
Of course, it will generate Javadoc only when in the correct places. Javadoc also has a pretty well defined format, see here.
The /** denotes "documentation" comments; Javadocs etc. look for these when creating documentation for your code.
So they should really only be used above methods and classes, e.g.:
/**
* Class to represent tigers.
*/
class Tiger {
/**
* Go extinct.
*/
void goExtinct() {
}
}
The /* variant just denotes a standard comment block.
Yep, it's the javadoc notation to use /** Primary sentence. Other descriptions... */. First sentece up to the . will be used in summaries of javadoc and the rest in the detailed view.
Javadoc treats /** differently; classes and methods which have /** comments above them will get put into javadoc output.
If you use the reference formatting (e.g. {#link ClassA}) and rename the class ClassA with Eclipse, it will automatically update the comment if it is a javadoc comment.