A comment must be placed just before the declaration which it describes. By default, adjoining comments separated only be whitespace are joined into one comment. This behaviour may be controlled by the --join-comments command line switch. See command line options.
Comments may be formatted by means of comment-commands. A comment-command starts with '@' followed by the command name. Command names are not case-sensitive.
If no commands are present in the whole comment, then the comment is simply written under the heading 'Description'. By default, the first sentence is used as the synopsis. The synopsis may be also specified by the @synopsis command.
Commands may be divided into three groups: section commands, inline commands and comment-start commands.
Section commands begin a new section - typically a new paragraph. Everything after a section command falls into the new section. The old one is finished. If an unknown command is encountered, a warning is issued and a new section is started with the name of the unrecognized command, capitalized and with '-' and '_' changed into space, as the heading for the section.
One of the most common section commands is probably the @see command. It begins a new section of whitespace- or comma-separated names of identifiers, which are displayed as links under the heading 'See also'.
Inline commands appear inside a section and don't terminate it. Two of these commands are, for instance, @code and @end-code. These two commands are used to indicate that the text between them is a program code.
Comment-start commant are interpreted only if they appear at the very start of the comment. The '@' character must be the first character of the comment. There are currently only two such commands: @discard, which causes the comment to be discarded, and @decl, which makes the rest of the comment be treated like a declaration.
Comment-start commands, in contrast to the other two flavours of commands, apply only to one comment as found in a source file, regardless of whether adjoining comments are to be joined or not.
It is worth noting that if you place an ordinary command at the very beginning of the comment, it will be tried to be interpreted as a comment-start command and an error will occur.
For more details on available commands and their complete list see the command list.