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