Java: Purpose of annotations in comments?

Question

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.

Answer 1

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