Writing tag parameters without parenthesis

You can also specify tag parameters without enclosing them in parenthesis. So you can write

{ @param S is the text to print
  @raises EMyException sometimes }
procedure Print(const S: string);

and it is equivalent to

{ @param(S is the text to print)
  @raises(EMyException sometimes) }
procedure Print(const S: string);

Parsing logic is simple: If a tag requires some parameters but you do not put an opening parenthesis '(' char right after it, then the tag’s parameters are supposed to span to the end of line (or to the end of comment). Note that this rule does not "break" the behavior of parameter-less tags like @name tag. Also it does not break comments that enclose tag parameters in parenthesis.

Multiline parameters without parenthesis are also possible with the help of "line feed" char '\'. Put this char at the end of line and parameter will spread over line feed to the next line. This mechanism is similar to that used in shell scripts, C language and so on.

{ @param S is the text to print. \
    It should not contain non-printable characters.
  @raises EMyException sometimes }
procedure Print(const S: string);

For more comments and examples of use you can take a look at test unit for this feature.

Advantages of not enclosing tag parameters in parenthesis are

  • sometimes this tends to look better in unit source

  • compatibility with JavaDoc and others