-------------------------------------------------------------------------------- A list of commands recognized by SrcDoc. -------------------------------------------------------------------------------- Note: Arguments may be passed to commands in two ways. The first one is to enclose the whole command list in braces ("(" and ")") and separate the arguments with commas. In this case, the leading whitespace before each argument are removed. Starting from the first non-whitespace character up to ")" or "," every character is then considered to be a part of the argument, including whitespace. We shall call the arguments passed in this way explicit arguments. The second way is just to write the arguments after the command name separating them with whitespace. In this approach, however, the number of the following words interpreted as arguments is precisely defined by the command. That is, depending on the command, different numbers of subsequent words are considered to be arguments. We shall call the arguments passed in this way implicit arguments. The notation @cmd arg1 arg2 ... argN means that the command cmd takes exactly N implicit arguments. These arguments may be as well passed as explicit arguments. The notation @cmd(arg1, arg2, ..., argN) means that the command cmd takes exactly N explicit arguments. These arguments cannot be passed as implicit arguments. All commands are case-insensitive. -------------------------------------------------------------------------------- Alphabetical list of commands <xxx> Indicates that xxx is a name of some local symbol (ex. a routine parameter). xxx must be a single word and may contain no whitespace. _xxx_ Makes xxx emphasised. See @emphasis. \<char> If <char> is one of '_', '<', '>', '@' or '\' then escapes it, i.e. prevents it from being specially interpreted by the comment parser. '@' may also be escaped by another '@'. @<xxx> Creates a link to xxx. See @link. @c @code Makes the subsequent text be interpreted as source code and formatted accordingly. See @end-code. @discard-subsequent-commands @discard-commands Discards all the commands after the current position. In other words, interprets every subsequent @ character as a normal character. @discard-recent-comment @discard-recent-comments @discard-comment Discards the part of the comment before the current position. @e <word> @emp <word> @emphasis <word> @emphasis(text) Makes <word> or <text> emphasised. <word> may not contain whitespace and must be composed of alpha-numeric characters entirely. <text> may contain anything except for ',' and ')'. @ec @end-code If @code is active then deactivates it. Otherwise does nothing. @fetch-related Fetches a comment from a related method and prepends it to the current comment. A related method is a method in an ancestor class or an implemented interface or its ancestor with the same name as the current method. @heading one_word_heading size @heading(heading, size) @heading(heading) Makes <heading> appear as a heading of size <size>. <size> may be a number form 1 (the largest) to 6 (the smallest). If the size is omitted then uses the size number 3. @ignore-declarations n Ignores n following declarations. Comments are read and processed normally, and if one of the following comment includes an @include-declarations command it overrides the effect of the previous command. @include-declarations n Indicates that the current comment is a common comment for n following declarations. @id name @identifier name Interprets <name> as a programming language identifier and formats it accordingly. @kw arg @keyword arg Indicates that the argument arg is a language keyword. It will be formatted accordingly. @link dest @link(dest,label) Creates a link to <dest>. <dest> should be the name of an identifier, either qualified or not. If <dest> is not recognized as a valid symbol then the link is written as a plain text. The text on the link is <label> if the second argument is present. @linkfile dest @linkfile(dest,label) @lf dest @lf(dest,label) Creates a link to a file named <dest>. Causes the documentation to be generated for this file as well. @nl @newline Insert a line break. @no-description Inhibits the automatic generation of the description paragraph for the current comment. @para @para(heading) Starts a new paragraph without a heading or with <heading> as a heading. When starting a new paragraph text formatting options are reset to their defaults. @param param_name [-] param_description... Declares a parameter to a routine. param_name is the name of the parameter, followed by an optional dash (-), followed by the description of the parameter, which is a text block of any length continuing up to the next non-inline command or the end of the comment. @pre ... @endpre Declares a pre-formatted text block. Anything between the @pre and @endpre commands is written to the output file exactly as it appears in the comment. No formatting, beautifying or even not the interpretation of commands is performed. The only recognized command after encountering @pre is @endpre. @profile <profile_name> @profile(<profile_names>) @profiles(<profile_names>) Indicates that _all_ of the declarations that will be associated with the comment should be written out only in the listed profiles. If this appears in the unit comment then the documentation for the whole unit is created only in the listed profiles. There are two predefined profile names: 'user' and 'devel'. To exclude the declaration from all profiles use '@profile none'. Profile names are not case-sensitive. @see [block] Begins a new paragraph with the heading 'See' and creates a link to each word in [block]. Discards any non-alphanumerical characters in [block]. @synopsis [block] Declares the synopsis for the current comment to be [block]. If there is no @synopsis command in the whole comment and the --synopsis command line option is on (the default), then the first sentence of the comment is assumed to be the synopsis, provided that it is not too long. @title(title) Sets the title for the comment. If this appears in a file whose only content is a comment then this sets the name by which the file is referred to in the auto-generated contents. Otherwise, it might or might not have any effect depending on the output format and the size of the declaration/section associated with the comment. @until-next-comment Indicates that the current comment is a common comment for all following declarations until another comment is encountered. Comment-start Commands These commands are interpreted only if they appear at the very beginning of a comment. Not even a preceding sequence of whitespace is allowed. The @ character must be the first character of the comment. {@discard ... } Ignores the comment. Applies only to one, separate comment, even when comments are joined. For example, from the following two comments only the first one is ignored, even if adjoining comments are merged. {@discard A comment to ignore. } { This one is not ignored. } {@decl <declaration> } The effect of this comment is that anything after it in the comment is treated af if it was outside a comment. It is often useful when a declaration in a descendant class is not overridden, but nonetheless needs a different description than that in the ancestor.