comments.html

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

    <p>Depending on the logic of the identifier to be commented this sections
       are evaluated and inserted into the documentation. &quot;~~&quot; is
       treated as a single tilde, it is quoted with itself. &quot;~[[&quot; is
       replaced with &quot;[&quot; and &quot;~[]&quot; is replaced with
       &quot;]&quot;. &quot;~[command ... ]&quot; is a command and is replaced
       with the text it produces, i.e.:<br>
       <code>~[command Param1 Param2 And an arbitrary text and maybe other
       commands.]</code><br>
       The whole bracket is replaced by the text produced by the command.<br>
       As already mentioned these characters can also be changed in
       of the <a href="options.html#OptionTJaddCommentData">the options of the
       scanner of comments</a>.</p>

       Supported commands so far:
       <dl>
         <dt>~[ Text]</dt>
           <dd>The text is used as is (neutral command). Can be used to pass
               parameters with whitespaces in it to another command.</dd>
         <dt><a name="icLink">~[link Identifier[:Index] [Text]]</a></dt>
           <dd>A link on the identifier is inserted instead. If no text is
               given the text of the identifier is used for the link, if a
               whole path is used like in the following examples, each part
               (separated by the dots ".") will have a link to the identifier
               or file of that part.<br>
               For overloaded functions the index of the method can be
               specified after a colon, the index is one-based counted in the
               same order as the functions are defined. For methods, however,
               note that they won't be searched in ancestor-classes.</dd>
         <dt>~[link .Member[:Index] [Text]]</dt>
           <dd>The same for fields/methods etc. of the current
               class/record/etc.</dd>
         <dt>~[link Member.SubMember.SubSubMember.SubSubSubMember]</dt>
           <dd>Here we can see a path to the final member. For each of the
               components/parts of the path a link to the appropriate
               identifier is made.</dd>
         <dt>~[link Identifier.Member[:Index] [Text]]</dt>
           <dd>Another example</dd>
         <dt>~[link File.Identifier[:Index] [Text]]</dt>
           <dd>Another example</dd>
         <dt>~[link File.Identifier.Member[:Index] [Text]]</dt>
           <dd>Another example</dd>
         <dt>~[linkClass ClassIdentifier [Text]]</dt>
           <dd>A class (record/interface/etc.) with that name is searched and a
               link to it created.</dd>
         <dt>~[linkUnit FileName [Text]]</dt>
           <dd>A file with that (internal) name is searched and a link to it
               created (yes, should be linkFile).</dd>
         <dt>~[linkExtern URI [Text]]</dt>
           <dd>Inserts a link to an external (outside the generated
               documentation) URI.</dd>

         <dt>~[defineText Doc_Text_Name Text]</dt>
           <dd>Save the text with the name Doc_Text_Name internally.
               This works mostly like a variable in Delphi.</dd>
         <dt>~[defineTextIf Text1 [_]Operator Text2 Doc_Text_Name Text]</dt>
           <dd>Save the text with the name Doc_Text_Name internally if Text1
               and Text2 are in the relation expressed by Operator. If it
               starts with an underscore &quot;_&quot both texts are changed to
               lower case before doing the comparison.</dd>
         <dt>~[insertText Doc_Text_Name]</dt>
           <dd>Inserts the internally saved text.
               This works mostly like a variable in Delphi.</dd>
         <dt>~[optionSupported Option_Name Text]</dt>
           <dd>Inserts the contained text in the documentation only if an
               option with the specified name is supported by one of the
               objects used to generate it.</dd>
         <dt>~[optionValue Option_Name [Fail-Text]]</dt>
           <dd>Inserts the value of the option with the specified name of one
               of the objects used to generate the documentation. If the option
               is not supported the content of the node will be inserted
               instead.</dd>
         <dt>~[insertVariable Doc_Variable_Name]</dt>
           <dd>Inserts the text expressed by Doc_Variable_Name. This text is
               provided by the generator, it's not a user variable like in
               <code>~[insertText Doc_Text_Name]</code>, instead the value of
               it is variable, it depends on the place and time it is used. See
               below for an enumeration of all available names.</dd>
         <dt>~[includeFile FilePath [Fail-Text]]</dt>
           <dd>Inserts the content of the given file, if this is not possible
               the following text is inserted instead. The content is inserted
               directly, so it should be compatible with the format of the
               generator and it should fit into that current place in the
               documentation. If the file is not found a warning message will
               be logged.</dd>
         <dt>~[inheritDoc]</dt>
           <dd>Inherits the documentation of the section from an ancestor if
               possible. It's only possible with class/object/interface's with
               a documented ancestor or an overridden method of a such or a
               redeclaration of a property. In addition it's only possible in
               the default section at the beginning of the comment and in the
               <code>~param</code> and <code>~result</code>-sections.</dd>

         <dt>~[em Text]</dt>
           <dd><em>Emphasizes</em> the text, in most cases (generators) this is
               done by formating it italic.</dd>
         <dt>~[code Text]</dt>
           <dd>Inserts the text as a (short) code segment.</dd>
         <dt>~[preformatted Text]</dt>
           <dd>Inserts the text as preformatted text (line breaks and indention
               is kept).</dd>
         <dt>~[sample Text]</dt>
           <dd>Inserts the text as a (longer) code sample, similar to
               <code>~[preformatted ~[code Text]]</code>.</dd>

         <dt>~[br]</dt>
           <dd>Inserts a line break.</dd>
         <dt>~[p]</dt>
           <dd>Inserts a paragraph break (ends the current paragraph). An empty
               line will also end the paragraph.</dd>



         <dt><a name="icuserdoc">~[userDoc FilePath [Fail-Text]]</a></dt>
           <dd>Reads the given file as general documentation of the project not
               associated with identifiers. If it can't be read the following
               text is returned, if it can nothing. If it has already be read
               the command is ignored. The content of the file is treated like
               a comment, the same syntax applies. The documentation has to be
               in <code>~page</code>-sections, each section representing a page
               of the documentation. The text in the initial section, i.e. not
               in a section, will be inserted in the index of the
               documentation, because of that it should be short (or
               nonexistent) and can be used f.e. to read other files of
               documentation. This inline command should not be used in
               <code>~page</code>-sections.</dd>
         <dt>~[linkPage PageName|PageNumber Text]</dt>
           <dd>Inserts a link to the page. The name or the number (beginning
               with zero) of the page can be specified. &quot;Index&quot; will
               always generate a link on the index of the documentation. The
               text is used as the text of the link. A few
               examples:<pre>~[linkPage Index Index of the Documentation]
~[linkPage 0 Link to first Page]
~[linkPage FirstPage Link to a Page called &quot;FirstPage&quot;]
~[linkPage ~[insertVariable ThisPageName] Link to this Page]
~[linkPage ~[insertVariable ThisPage] Link to this Page]
~[linkPage ~[add ~[insertVariable ThisPage] 1] Link to the next Page]
~[linkPage ~[add ~[insertVariable ThisPage] -1] Link to the previous Page]</pre>
           </dd>
         <dt>~[add addend1 addend2]</dt>
           <dd>Adds both values and inserts the result instead. Should be used
               in conjunction with <code>~[linkPage ]</code> to link to pages
               relative to the current page.</dd>
         <dt>~[HelpContext number]</dt>
           <dd>Sets the help context for the current topic. If not a Windows
               Help file or Windows HTML Help file is generated this command is
               ignored. This inline command is probably most useful in the
               user documentation when generating the help on a GUI.</dd>
         <dt>~[linkGUI TopicName Text]</dt>
           <dd>Inserts a link to the topic of documentation as a help on a GUI.
               Of course this only make sense if the documentation is generated
               as that. The TopicName has the format
               <code>[File][#Topic]</code>. File is the documented file to
               which the documentation is generated, if it is not specified
               the current file will be used. #Topic is the name of the topic
               of documentation within the file, if it is not specified or just
               "#" a link to the screen shot is generated. "#.default" will
               generate a link to the default topic. At least the file or the
               topic within the (current) file has to be specified.</dd>


         <dt><a name="icimage">~[image [Alignment=char]
                                       [ConvFormat/Ext=JPEG|JPG]
                                       [Resolution=WxH|0x0]
                                       Drive\Path\ImageFile[.ext]
                                       [Alternative Text]
                                       ~[imageLink ...]* ]</a></dt>
           <dd>Inserts an image in the documentation. There are several
               parameters fo this command but only one is mandatory, the name
               of the image file itself. It can be specified with an absolute
               or relative path, the extension ".bmp" will be appended
               automatically if missing. The most interesting optional
               parameter is the first one, the alignment. By default the image
               is inserted centered in an own paragraph in the documentation,
               by specifying "char" as the first parameter, this will be
               overridden, and the image will be inserted like a normal
               character inside the current line.<br>
               The second parameter is only used if HTML or PDF files are
               generated to specify whether the image should be converted to a
               JPEG file instead of a PNG file. JPEG files give a better
               compression ratio for "real live" pictures, like a photo of the
               developer(s), but due to lossy compression it is not that suited
               for technical images like diagrams etc. which can be better
               compressed per pixel like in the PNG format. The third parameter
               can be used to specify the resolution of an image, if it is not
               a bitmap file. This is currently not supported, so the
               resolution will be ignored.<br> 
               Whether a parameter denotes one of the optional parameters is
               checked by its text. Append the file extension if you want to
               insert an image called "char", "JPG", "JPEG" or for example
               "45x65".<br>
               The alternative text is ignored in most cases, it is used only
               in HTML files, but even there it is mostly hidden. Inside this
               text the inline command ~[imageLink ...] can be used to generate
               links inside the image, see below for more information.<br>
               This command is not supported in the
               L<small><sup>A</sup></small>T<small><sub>E</sub></small>X
               generator and will be ignored with a warning message.</dd>
         <dt><a name="icimageLink">~[imageLink "all"|Left,Top,Right,Bottom
                                               Link-InlineCommand
                                               LinkTarget
                                               [Alternative Text]]</a></dt>
           <dd>Inserts a link inside the current image, i.e. can only be used
               inside the inline command ~[image ]. The first parameter denotes
               the region of the image to generate the link on. If it is the
               text "all" or "whole" the link in generated on the whole image,
               if that is the case only one single link on the image is
               allowed. Else the positions of a rectangle inside the image
               (in pixels) should be specified like used from the type
               <code>TRect</code>. Several of these links can be specified
               inside an image, the most specific ones should be first and the
               most general ones the last ones. The second parameter is the
               name of an inline command to create the link: link, linkUnit,
               linkClass, linkExtern, linkPage, linkGUI. The third is the
               target to link to, this is the same as the first parameter for
               the specified inline command to create the link. The alternative
               text is ignored in most cases, it is used only in HTML files,
               but even there it is mostly hidden.</dd>

         <dt><a name="icdiagram">~[diagram Parameter*]</a></dt>
           <dd><p>Creates a diagram of the files or classes of the parsed
                 source code and inserts it in the documentation. The
                 parameters can either be options, indicated by a leading