SourceForge.net Logo Homepage: http://delphidoc.sourceforge.net/
Project-Page: http://sourceforge.net/projects/delphidoc/


JADD - Just Another DelphiDoc

Back to the main page or the manual.

Comments

This page describes the possibilities in the comments of the projects you would like DelphiDoc to document. This means where the comments are searched and what sections and commands are possible within the comments to enrich the documentation.

The source code of DelphiDoc itself is fully commented according to the possibilities outlined in here. If you need examples, please take a look at it.

Table of Contents

General

Comments are expected to be directly above the identifiers or on the same line. This is the main requirement for comments. They don't have to be tagged specially (f.i. by one or more stars "*") to be considered by DelphiDoc. If for example a procedure is commented several sections are expected, f.i. to describe the parameters. If they are not found a warning will be logged but it will nevertheless be documented. That is why even for not especially for DelphiDoc commented projects documentation can be generated. But the (correct) comments will only be used if they are at the above mentioned position. But even without comments a useful documentation can be created; through the generated linking an overview of the relations of the identifiers can be generated.

There are several generators to generate completely different formats, for this reason no native code of a format may be used, it would break in other formats. There are several inline commands to format text and add special things to the generated documentation that will work in every format.
As there are a few other tools out there which seem to only generate documentation in HTML format and allow the use of those tags within the comments, the generators of HTML also have an option to use these tags without change.

Sections

Comments are parsed, therefore they are split up in sections at first. The character "~" (the tilde) is the special character, this can be changed in the options of the extractor.
Sections are initiated by ~sectionname, you can also change these names via the options of the extractor, as you can change the special character "~".

Syntax and Semantic of the Sections:

     Text
The default section contains the normal documentation. In some cases the first sentence (at the moment only for functions in the HTML-generator) will be used as an abstract.
~deprecated [Text]
Marks the identifier/the file as deprecated. This means it shouldn't be used anymore and it will/would be deleted. The possibly following text will be added to the documentation.
~todo Text
The text is added to the documentation and the identifier/file is added to a list of things that still have to be done.
~feature Text
The text is added to the documentation and the identifier/file is added to a list of features that can/should/could be added.
~see Identifier[:Index] [Text]
A link on the given identifier is inserted in the documentation, same syntax as with ~[link ]. A possibly following (short) text (f.e. a reason) is also inserted. This section can be present several times.
~seeText Text
The text will also be inserted. Though it can be longer, it is thought for short external links, f.i. to the help of Delphi. This section can also be present several times.
~param ParamName[, ParamName]* Text
The text is used as documentation for the given parameter(s). The text is evaluated for each parameter separately so that f.i. a ~[inheritDoc] always evaluates to a different and correct text. Usually there should be one section for each parameter.
~result/return/returns Text
The documentation of the result of a function or function type.
~exception/throws/raises ExceptionType Text
This section gives the type of an exception that could be thrown by a function with an explanation when this could happen. It can be present several times.
~example Text
An example to the identifier is given with this section. The given text is inserted as an example in the documentation but treated as normal text, that means code has to be formatted as such (see below) if it is inside this section. This section can be present several times.
~author
Creates an entry (or a list) with the following text.
~version
Creates an entry (or a list) with the following text.
~??? (additional attributes)
Creates an entry (or a list) with the following text. The names of the section have to be defined in the options of the extractor named SectionName_AdditionalAttribute1. There are three additional attributes defined so far. The headers for the list can be defined by "localizing" the texts CommentAdditionalAttribute1 etc..
~page PageName (Title of Page) Text
This section is only valid in files read with ~[userDoc FilePath] to document the project not associated with identifiers. To be exact the documentation ought to be in sections of this kind. Each section represents a page of documentation. The first argument is the name of the page, what can be used to create links to it by ~[linkPage PageName]. The remnant of the line or, if it is empty the whole next non-empty line, is used as the title of the page. The name "Index" is reserved for the index of the documentation. No inline commands may be used within the name or the title.
~guiInclude NameOfFile
This section is only valid in text files with documentation as a help on a GUI. Should in general be at the top of the file. The denoted file is read as if it were part of the text file itself.
~guiAlias Alias RealName
This section is only valid in text files with documentation as a help on a GUI. Should in general be at the top of the file after ~guiInclude. It defines an alias for components, i.e. instead of generating a link to the documentation of the component Alias a link to the documentation of RealName is generated. As the help context of the components using a documentation topic is used for it, all components using a topic must have the same help context, i.e. both components Alias and RealName in this example. The RealName may also be a defined alias, but there shouldn't be any circular aliases.
~guiManual Left,Top,Right,Bottom Link
This section is only valid in text files with documentation as a help on a GUI. Should in general be before any ~gui sections. It defines an additional link region in the screen shot, with that it has some similarities with the inline command ~[imageLink ]. The coordinates are integer values in pixels inside the screen shot. The link should be the name of a documentation topic as defined by a ~gui section. If it is not a known documentation topic it will be treated as an URI in the WWW and a warning message will be logged.
~gui TopicName (Title of Topic) Text
This section is only valid in text files with documentation as a help on a GUI. Should in general be after any other sections in the file. The name is the name of the component to be documented and is used in any link in the screen shot (from the log file and any manual link with ~guiManual) and in the inline command ~[linkGUI ]. The remnant of the line or, if it is empty the whole next non-empty line, is used as the title for the topic of documentation. No inline commands may be used within the name or the title. There should be a topic for each component that is not aliased to another one.
There are three special topic names: .preface, .epilogue and .default. The preface will be inserted above the screen shot and sometimes above all topics (depending on the generator), the epilogue accordingly after the screen shot and maybe after each topic. Default describes the default comment for any component that is not documented.

Inline Commands

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

Supported commands so far:
~[ Text]
The text is used as is (neutral command). Can be used to pass parameters with whitespaces in it to another command.
~[link Identifier[:Index] [Text]]
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.
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.
~[link .Member[:Index] [Text]]
The same for fields/methods etc. of the current class/record/etc.
~[link Member.SubMember.SubSubMember.SubSubSubMember]
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.
~[link Identifier.Member[:Index] [Text]]
Another example
~[link File.Identifier[:Index] [Text]]
Another example
~[link File.Identifier.Member[:Index] [Text]]
Another example
~[linkClass ClassIdentifier [Text]]
A class (record/interface/etc.) with that name is searched and a link to it created.
~[linkUnit FileName [Text]]
A file with that (internal) name is searched and a link to it created (yes, should be linkFile).
~[linkExtern URI [Text]]
Inserts a link to an external (outside the generated documentation) URI.
~[defineText Doc_Text_Name Text]
Save the text with the name Doc_Text_Name internally. This works mostly like a variable in Delphi.
~[defineTextIf Text1 [_]Operator Text2 Doc_Text_Name Text]
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 "_" both texts are changed to lower case before doing the comparison.
~[insertText Doc_Text_Name]
Inserts the internally saved text. This works mostly like a variable in Delphi.
~[optionSupported Option_Name Text]
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.
~[optionValue Option_Name [Fail-Text]]
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.
~[insertVariable Doc_Variable_Name]
Inserts the text expressed by Doc_Variable_Name. This text is provided by the generator, it's not a user variable like in ~[insertText Doc_Text_Name], 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.
~[includeFile FilePath [Fail-Text]]
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.
~[inheritDoc]
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 ~param and ~result-sections.
~[em Text]
Emphasizes the text, in most cases (generators) this is done by formating it italic.
~[code Text]
Inserts the text as a (short) code segment.
~[preformatted Text]
Inserts the text as preformatted text (line breaks and indention is kept).
~[sample Text]
Inserts the text as a (longer) code sample, similar to ~[preformatted ~[code Text]].
~[br]
Inserts a line break.
~[p]
Inserts a paragraph break (ends the current paragraph). An empty line will also end the paragraph.
~[userDoc FilePath [Fail-Text]]
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 ~page-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 ~page-sections.
~[linkPage PageName|PageNumber Text]
Inserts a link to the page. The name or the number (beginning with zero) of the page can be specified. "Index" will always generate a link on the index of the documentation. The text is used as the text of the link. A few examples:
~[linkPage Index Index of the Documentation]
~[linkPage 0 Link to first Page]
~[linkPage FirstPage Link to a Page called "FirstPage"]
~[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]
~[add addend1 addend2]
Adds both values and inserts the result instead. Should be used in conjunction with ~[linkPage ] to link to pages relative to the current page.
~[HelpContext number]
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.
~[linkGUI TopicName Text]
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 [File][#Topic]. 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.
~[image [Alignment=char] [ConvFormat/Ext=JPEG|JPG] [Resolution=WxH|0x0] Drive\Path\ImageFile[.ext] [Alternative Text] ~[imageLink ...]* ]
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.
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.
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".
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.
This command is not supported in the LATEX generator and will be ignored with a warning message.
~[imageLink "all"|Left,Top,Right,Bottom Link-InlineCommand LinkTarget [Alternative Text]]
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 TRect. 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.
~[diagram Parameter*]

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 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.

The following options are possible:
font=Name
The name of the font to use to display the diagram. If the name contains spaces, they can be replaces by stars "*".
size=Size
The size of the font to use to display the diagram.
margin=Margin
The margin in pixels to use to display the boxes and to automatically lay-out the diagram.
class
A diagram of classes (record-like types: record, object, class, interface, dispinterface) should be generated. This is the default.
file
A diagram of files should be generated.
layout=sugiyama|simple|postprocess
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.
implementation=True|False
Only in diagrams of files: Whether the usage of units in the implementation part of other units should be shown.
types=set
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 (record, object, class, interface, dispinterface).
showprivate=True|False
Only in diagrams of files: Whether record-like types not defined in the interface of a unit should be shown.
associations=True|False
Only in diagrams of classes: Whether associations between classes should be shown.
showfile=True|False
Only in diagrams of classes: Whether the files of the classes should be shown.
members=[set]
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 (fields, methods, properties).
scopes=[set]
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 (automated, published, public, protected, private).
result=True|False
Only in diagrams of classes: Whether the types of the results of methods should be shown.
parameter=True|False
Only in diagrams of classes: Whether the declarations of the lists of parameters of methods should be shown.

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 init[.modifiers]*, 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.

First how to start a set of files:
"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.
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.

How to start a set of classes:
"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".
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 +TTheClass.interfaces.filter(I).

Pre-defined Texts

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

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

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.

Variable Texts

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

The End

Well, if you made it up to this point you may want to take a look at the styleguide of Javadoc. While the internal commands are somehow different and you shouldn't use HMTL code for DelphiDoc (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.