Class TDocGenerator

the (human) output language of the documentation file(s)

list of all units that were successfully parsed

Return a link to item Item which will be displayed as LinkCaption. Returned string may be directly inserted inside output documentation. LinkCaption will be always converted using ConvertString before writing, so don't worry about doing this yourself when calling this method.

LinkContext may be used in some descendants to present the link differently, see TLinkContext for it's meaning.

If some output format doesn't support this feature, it can return simply ConvertString(LinkCaption). This is the default implementation of this method in this class.

This writes Code as a Pascal code. Links inside the code are resolved from Item. If WriteItemLink then Item.Name is made a link. Item.Name is printed between NameLinkBegin and NameLinkEnd.

If field CurrentStream is assigned, it is disposed and set to nil.

Makes a String look like a coded String, i.e. <CODE>TheString</CODE> in Html.

Parameters

s

is the string to format

Returns

the formatted string

Converts for each character in S, thus assembling a String that is returned and can be written to the documentation file.

The @ character should not be converted, this will be done later on.

Converts a character to its converted form. This method should always be called to add characters to a string.

@ should also be converted by this routine.

This function is supposed to return a reference to an item, that is the name combined with some linking information like a hyperlink element in HTML or a page number in Tex.

Open output stream in the destination directory. If CurrentStream still exists (<> nil), it is closed. Then, a new output stream in the destination directory is created and assigned to CurrentStream. The file is overwritten if exists.

Use this only for text files that you want to write using WriteXxx methods of this class (like WriteConverted). There's no point to use if for other files.

Returns True if creation was successful, False otherwise. When it returns False, the error message was already shown by DoMessage.

Searches for an email address in String S. Searches for first appearance of the @ character

Searches for a web address in String S. It must either contain a http:// or start with www.

Searches all items in all units (given by field Units) for item with NameParts. Returns a pointer to the item on success, nil otherwise.

GetClassDirectiveName returns ' abstract', or ' sealed' for classes that abstract or sealed respectively. GetClassDirectiveName is used by TTexDocGenerator and TGenericHTMLDocGenerator in writing the declaration of the class.

GetCIOTypeName writes a translation of MyType based on the current language. However, 'record' and 'packed record' are not translated.

Loads descriptions from file N and replaces or fills the corresponding comment sections of items.

Searches for item with name S.

If S is not splittable by SplitNameParts, returns nil. If WarningIfNotSplittable, additionally does DoMessage with appropriate warning.

Else (if S is "splittable"), seeks for S (first trying Item.FindName, if Item is not nil, then trying FindGlobal). Returns nil if not found.

Searches for an item of name S which was linked in the description of Item. Starts search within item, then does a search on all items in all units using FindGlobal. Returns a link as String on success.

If S is not splittable by SplitNameParts, it always does DoMessage with appropriate warning and returns something like 'UNKNOWN' (no matter what is the value of WarningIfLinkNotFound). FoundItem will be set to nil in this case.

When item will not be found then:

• if WarningIfLinkNotFound is true then it returns CodeString(ConvertString(S)) and makes DoMessage with appropriate warning.

• else it returns '' (and does not do any DoMessage)

If LinkDisplay is not '', then it specifies explicite the display text for link. Else how exactly link does look like is controlled by LinkLook property.

Parameters

FoundItem

is the found item instance or nil if not found.

Just like previous overloaded version, but this doesn't return FoundItem (in case you don't need it).

Writes S to CurrentStream, converting it using ConvertString. Then optionally writes LineEnding.

Writes S to CurrentStream, converting it using ConvertString. No LineEnding at the end.

Writes S to CurrentStream, converting it using ConvertString. Then writes LineEnding.

Simply writes T to CurrentStream, with optional LineEnding.

Simply writes T to CurrentStream.

Simply writes T followed by LineEnding to CurrentStream.

Abstract method that writes all documentation for a single unit U to output, starting at heading level HL. Implementation must be provided by descendant objects and is dependent on output format.

Writes documentation for all units, calling WriteUnit for each unit.

output graphviz uses tree

output graphviz class tree

starts the spell checker

If CheckSpelling and spell checking was successfully started, this will run FAspellProcess.CheckString and will report all errors using DoMessage with mtWarning.

Otherwise this just clears AErrors, which means that no errors were found.

closes the spellchecker

FormatPascalCode will cause Line to be formatted in the way that Pascal code is formatted in Delphi. Note that given Line is taken directly from what user put inside @longcode, it is not even processed by ConvertString. You should process it with ConvertString if you want.

This will cause AString to be formatted in the way that normal Pascal statements (not keywords, strings, comments, etc.) look in Delphi.

FormatComment will cause AString to be formatted in the way that comments other than compiler directives are formatted in Delphi. See: FormatCompilerComment.

FormatHex will cause AString to be formatted in the way that Hex are formatted in Delphi.

FormatNumeric will cause AString to be formatted in the way that Numeric are formatted in Delphi.

FormatFloat will cause AString to be formatted in the way that Float are formatted in Delphi.

FormatString will cause AString to be formatted in the way that strings are formatted in Delphi.

FormatKeyWord will cause AString to be formatted in the way that reserved words are formatted in Delphi.

FormatCompilerComment will cause AString to be formatted in the way that compiler directives are formatted in Delphi.

This is paragraph marker in output documentation.

Default implementation in this class simply returns ' ' (one space).

See TTagManager.ShortDash. Default implementation in this class returns '-'.

See TTagManager.EnDash. Default implementation in this class returns '--'.

See TTagManager.EmDash. Default implementation in this class returns '---'.

S is guaranteed (guaranteed by the user) to be correct html content, this is taken directly from parameters of tag. Override this function to decide what to put in output on such thing.

Note that S is not processed in any way, even with ConvertString. So you're able to copy user's input inside @html() verbatim to the output.

The default implementation is this class simply discards it, i.e. returns always ''. Generators that know what to do with HTML can override this with simple "Result := S".

This is equivalent of HtmlString for @latex tag.

The default implementation is this class simply discards it, i.e. returns always ''. Generators that know what to do with raw LaTeX markup can override this with simple "Result := S".

This returns markup that forces line break in given output format (e.g. '<br>' in html or '\\' in LaTeX).

It is used on
tag (but may also be used on other occasions in the future).

In this class it returns '', because it's valid for an output generator to simply ignore
tags if linebreaks can't be expressed in given output format.

This should return markup upon finding URL in description. E.g. HTML generator will want to wrap this in <a href="...">...</a>.

Note that passed here URL is not processed by ConvertString (because sometimes it could be undesirable). If you want you can process URL with ConvertString when overriding this method.

Default implementation in this class simply returns ConvertString(URL). This is good if your documentation format does not support anything like URL links.

WriteExternal is used to write the introduction and conclusion of the project.

This is called from WriteExternal when ExternalItem.Title and ShortTitle are already set, message about generating appropriate item is printed etc. This should write ExternalItem, including ExternalItem.DetailedDescription, ExternalItem.Authors, ExternalItem.Created, ExternalItem.LastMod.

WriteConclusion writes a conclusion for the project. See WriteExternal.

WriteIntroduction writes an introduction for the project. See WriteExternal.

FormatSection writes a section heading and a link-anchor;

FormatAnchor writes a link-anchor;

This returns Text formatted using bold font.

Given Text is already in the final output format (with characters converted using ConvertString, @-tags expanded etc.).

Implementation of this method in this class simply returns Result := Text. Output generators that can somehow express bold formatting (or at least emphasis of some text) should override this.

See also

FormatItalic

This returns Text formatted using italic font.

This returns Text formatted using italic font. Analogous to FormatBold.

This returns Text preserving spaces and line breaks. Note that Text passed here is not yet converted with ConvertString. The implementation of this method in this class just returns ConvertString(Text).

This should return markup upon including specified image in description. FileNames is a list of alternative filenames of an image, it always contains at least one item (i.e. FileNames.Count >= 1), never contains empty lines (i.e. Trim(FileNames[I]) <> ''), and contains only absolute filenames (already expanded to take description's unit's path into account).

E.g. HTML generator will want to choose the best format for HTML, then somehow copy the image from FileNames[Chosen] and wrap this in <img src="...">.

Implementation of this method in this class simply returns Result := ExpandFileName(FileNames[0]). Output generators should override this.

Format a list from given ListData.

This should return appropriate content for given Table. It's guaranteed that the Table passed here will have at least one row and in each row there will be at least one cell, so you don't have to check it within descendants.

Override this if you want to insert something on @tableOfContents tag. As a parameter you get already prepared tree of sections that your table of contents should show. Each item of Sections is a section on the level 1. Item's Name is section name, item's Value is section caption, item's Data is a TStringPairVector instance that describes subsections (on level 2) below this section. And so on, recursively.

Sections given here are never nil, and item's Data is never nil. But of course they may contain 0 items, and this should be a signal to you that given section doesn't have any subsections.

Default implementation of this method in this class just returns empty string.

Creates anchors and links for all items in all units.

Expands description for each item in each unit of Units. "Expands description" means that TTagManager.Execute is called, and item's DetailedDescription, AbstractDescription, AbstractDescriptionWasAutomatic (and many others, set by @-tags handlers) properties are calculated.

Abstract function that provides file extension for documentation format. Must be overwritten by descendants.

Assumes C contains file names as PString variables. Calls LoadDescriptionFile with each file name.

Must be overwritten, writes all documentation. Will create either a single file or one file for each unit and each class, interface or object, depending on output format.

Callback receiving messages from generator.

This is usually used internally by TPasDoc class, that assigns it's internal callback here when using this generator. Also, for the above reason, do not make this published.

See TPasDoc.OnMessage for something more useful for final programs.

the (human) output language of the documentation file(s)

Name of the project to create.

"Generator info" are things that can change with each invocation of pasdoc, with different pasdoc binary etc.

This includes

• pasdoc's compiler name and version,

• pasdoc's version and time of compilation

See [https://github.com/pasdoc/pasdoc/wiki/ExcludeGeneratorOption]. Default value is false (i.e. show them), as this information is generally considered useful.

Setting this to true is useful for automatically comparing two versions of pasdoc's output (e.g. when trying to automate pasdoc's tests).

Show creation time in the output.

Title of the documentation, supplied by user. May be empty. See TPasDoc.Title.

Destination directory for documentation. Must include terminating forward slash or backslash so that valid file names can be created by concatenating DestinationDirectory and a pathless file name.

generate a GraphViz diagram for the units dependencies

generate a GraphViz diagram for the Class hierarchy

link the GraphViz uses diagram

link the GraphViz classes diagram

The meaning of this is just like --auto-abstract command-line option. It is used in ExpandDescriptions.

This controls SearchLink behavior, as described in [https://github.com/pasdoc/pasdoc/wiki/LinkLookOption].

This controls auto-linking, see [https://github.com/pasdoc/pasdoc/wiki/AutoLinkOption]