comments.html

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

                 slash "/", or some files or classes that should be added,
                 indicated by a "+", or removed "-" from the diagram. If the
                 first character is none of these three a "+" is assumed.</p>
               The following options are possible:
               <dl>
                 <dt>font=<i>Name</i></dt>
                   <dd>The name of the font to use to display the diagram. If
                       the name contains spaces, they can be replaces by stars
                       "*".</dd>
                 <dt>size=<i>Size</i></dt>
                   <dd>The size of the font to use to display the diagram.</dd>
                 <dt>margin=<i>Margin</i></dt>
                   <dd>The margin in pixels to use to display the boxes and to
                       automatically lay-out the diagram.</dd>
                 <dt>class</dt>
                   <dd>A diagram of classes (record-like types: record, object,
                       class, interface, dispinterface) should be generated.
                       This is the default.</dd>
                 <dt>file</dt>
                   <dd>A diagram of files should be generated.</dd>
                 <dt>layout=sugiyama|simple|postprocess</dt>
                   <dd>The algorithm to use to automatically lay-out the
                       diagram. Sugiyama's algorithm is the default. The simple
                       algorithm with postprocessing optimization can only be
                       used for diagrams of classes. Sugiyama's algorithm may
                       fail, if the diagram is too complex.</dd>

                 <dt>implementation=True|False</dt>
                   <dd>Only in diagrams of files: Whether the usage of units in
                       the implementation part of other units should be
                       shown.</dd>
                 <dt>types=<i>set</i></dt>
                   <dd>Only in diagrams of files: The kinds of record-like
                       types of the files to list. This is a set and can be
                       defined like an option of a generator, for instance
                       include the leading character (<b>r</b>ecord,
                       <b>o</b>bject, <b>c</b>lass, <b>i</b>nterface,
                       <b>d</b>ispinterface).</dd>
                 <dt>showprivate=True|False</dt>
                   <dd>Only in diagrams of files: Whether record-like types not
                       defined in the interface of a unit should be shown.</dd>

                 <dt>associations=True|False</dt>
                   <dd>Only in diagrams of classes: Whether associations
                       between classes should be shown.</dd>
                 <dt>showfile=True|False</dt>
                   <dd>Only in diagrams of classes: Whether the files of the
                       classes should be shown.</dd>
                 <dt>members=[set]</dt>
                   <dd>Only in diagrams of classes: The kinds of members of the
                       classes to show. This is a set and can be defined like
                       an option of a generator, for instance include the
                       leading character (<b>f</b>ields, <b>m</b>ethods,
                       <b>p</b>roperties).</dd>
                 <dt>scopes=[set]</dt>
                   <dd>Only in diagrams of classes: The scopes of members of
                       the classes to show. This is a set and can be defined
                       like an option of a generator, for instance like a
                       string of five binary digits. 11100 for instance will
                       only show automated, published and public members,
                       protected and private members will not be shown.
                       A string including a relevant character for each scope
                       can also be used (<b>a</b>utomated, publi<b>s</b>hed,
                       pu<b>b</b>lic, pro<b>t</b>ected, pri<b>v</b>ate).</dd>
                 <dt>result=True|False</dt>
                   <dd>Only in diagrams of classes: Whether the types of the
                       results of methods should be shown.</dd>
                 <dt>parameter=True|False</dt>
                   <dd>Only in diagrams of classes: Whether the declarations of
                       the lists of parameters of methods should be shown.</dd>
               </dl>
               <p>To add or remove files or classes from the diagram each
                 parameter depicts a set of them that will then be added or
                 removed. The syntax to create these sets is
                 <code>init[.modifiers]*</code>, i.e. a command to create a
                 list to start with (in the simplest case just one file or
                 class) and separated by dots "." like in Delphi zero or more
                 modifiers of this set. The possible modifiers and ways to
                 start the set are different for diagrams of files and
                 classes.<p>
               <p>First how to start a set of files:<br>
                 "library", "package", "program" or "unit" will initialize the
                 set with all files of that kind. Any other text will be
                 interpreted as the name of a file, the set will then be
                 initialized to include only this file.<br>
                 The sets can be modified by "used", "interface" or
                 "implementation". All files that are used by the files in the
                 set will be added to the set. "used" will add all used files,
                 "interface" and "implementation" only files used by units in
                 that particular part. By adding a star "*" directly after the
                 modifier these modifiers work recursively. The modifiers
                 "library", "package", "program" and "unit" can be used to
                 filter all files from the list that are not of the kind.</p>

               <p>How to start a set of classes:<br>
                 "file(name of file)" will include all classes in the file.
                 "type(kinds)" will include all classes (record-like types) of
                 the specified kinds, these kinds are a set that can be
                 specified like for the option "types" of this inline
                 command. Any other text will be interpreted as the name of a
                 class to add. Only the first found class will be added, but
                 the name of the file may be appended in braces, "TSomeClass"
                 will add the first class of that name,
                 "TSomeClass(InThisFile)" will add the class defined in the
                 file "InThisFile".<br>
                 To modify the sets "classes", "filter", "interfaces", "super"
                 and "tree" can be used. "classes" will add for each interface
                 of the set the classes that implement them directly. Likewise
                 "interfaces" will add all implemented interfaces of the
                 classes in the set. "super" will add all ancestors of the
                 types, and "tree" all descendants. "filter" is the only
                 modifier to use parameters, it will remove all record-like
                 types from the set, that are not of the kinds defined by the
                 parameter. The parameter is again a set that can be specified
                 like for the option "class" of this inline command. So if you
                 want all implemented interfaces of a class in the diagram but
                 not the class itself, you can write
                 <code>+TTheClass.interfaces.filter(I)</code>.</p>
               </dd>
       </dl>



    <h2><a name="PredefinedTexts">Pre-defined Texts</a></h2>

       The following texts are pre-defined, to be included by
       <code>~[insertText name]</code>:
       <dl>
         <dt>DocClass</dt>
           <dd>Inserts the name of the class of the generator that creates the
               documentation, at the moment this is either
               &quot;<code>TICHTMLDoc</code>&quot;,
               &quot;<code>TICHTMLHelpDoc</code>&quot;,
               &quot;<code>TICWinHelpDoc</code>&quot;,
               &quot;<code>TICPDFDoc</code>&quot;,
               &quot;<code>TICLaTeXDoc</code>&quot;,
               &quot;<code>THTMLDoc</code>&quot;,
               &quot;<code>THTMLHelpDoc</code>&quot;,
               &quot;<code>TWinHelpDoc</code>&quot;,
               &quot;<code>TLaTeXDoc</code>&quot; or
               &quot;<code>TPDFDoc</code>&quot;.</dd>
       </dl>

       <p>There are also texts for the extractor (&quot;ExtractorClass&quot;)
          and evaluator (&quot;EvaluatorClass&quot;) of comments, but
          there is currently only one of each, so it isn't that usefull,
          additionally there are going to be some changes.
          &quot;CommentClass&quot; can be defined alternatively to the
          evaluator for the new kind of generators, but there is also only one
          available right now.</p>

       <p>I'm currently thinking about customizing some things via defined
          texts, for instance add a variable text to return the current date in
          a format as defined by a defined text.</p>





    <h2><a name="VariableTexts">Variable Texts</a></h2>

       The following variable texts are defined, to be included by
       <code>~[insertVariable name]</code>:
       <dl>
         <dt>DefinitionColumn</dt>
           <dd>Inserts the column in that the current identifier has been
               defined in.</dd>
         <dt>DefinitionLine</dt>
           <dd>Inserts the line in that the current identifier has been defined
               in.</dd>
         <dt>FileName</dt>
           <dd>Inserts the (internal) name of the current file.
               <code>~[link ~[insertVariable FileName] In this File]</code>
               creates (usually) a link on the file itself.</dd>
         <dt>FileSize</dt>
           <dd>Inserts the size of the current file. The size may differ
               slightly from the actual size depending on the used end-of-line
               characters.</dd>
         <dt>FileType</dt>
           <dd>Inserts the type of the current file, i.e.:
               <code>unit, program, library</code> or
               <code>package</code>.</dd>
         <dt>ForwardDefinitionColumn</dt>
           <dd>Inserts the column in that the current identifier has been
               first defined in.</dd>
         <dt>ForwardDefinitionLine</dt>
           <dd>Inserts the line in that the current identifier has been first
               defined in.</dd>
         <dt>NumberOfLines</dt>
           <dd>Inserts the number of lines in the current file.</dd>
         <dt>ThisIdentifier</dt>
           <dd>Inserts the name of the current identifier.</dd>
         <dt>ThisClass</dt>
           <dd>Inserts the name of the current class.</dd>
         <dt>ThisPageName</dt>
           <dd>Returns the internal name of the current page, (in the user
               documentation) for instance to generate a link to it.</dd>
         <dt>ThisPage</dt>
           <dd>Returns the number of the current page (in the user
               documentation), for instance to generate a link to it or a page
               relativ to it (by adding/subtracting of a number with
               <code>~[add ]</code>).</dd>
       </dl>


    <h2><a name="TheEnd">The End</a></h2>

      <p>Well, if you made it up to this point you may want to take a look at
         the
         <a href="http://java.sun.com/j2se/javadoc/writingdoccomments/#styleguide">styleguide
         of Javadoc</a>. While the internal commands are somehow different and
         you shouldn't use HMTL code for <em>DelphiDoc</em> (the code itself
         will be visible in the final documentation instead of the formatting),
         you may find it worthwhile to orientate the style of the text itself
         to the style proposed by this guide.</p>

  </body>
</html>