Class TDocGenerator
Unit
Declaration
type TDocGenerator = class(TComponent)
Description
basic documentation generator object
This abstract object will do the complete process of writing documentation files. It will be given the collection of units that was the result of the parsing process and a configuration object that was created from default values and program parameters. Depending on the output format, one or more files may be created (HTML will create several, Tex only one).
Hierarchy
- TObject
- TPersistent
- TComponent
- TDocGenerator
Overview
Fields
FLanguage: TPasDocLanguages; |
|
FClassHierarchy: TStringCardinalTree; |
|
FUnits: TPasUnits; |
Methods
procedure DoError(const AMessage: string; const AArguments: array of const; const AExitCode: Word); |
|
procedure DoMessage(const AVerbosity: Cardinal; const MessageType: TPasDocMessageType; const AMessage: string; const AArguments: array of const); |
|
procedure CreateClassHierarchy; |
|
function MakeItemLink(const Item: TBaseItem; const LinkCaption: string; const LinkContext: TLinkContext): string; virtual; |
|
procedure WriteCodeWithLinksCommon(const Item: TPasItem; const Code: string; WriteItemLink: boolean; const NameLinkBegin, NameLinkEnd: string); |
|
procedure CloseStream; |
|
function CodeString(const s: string): string; virtual; abstract; |
|
function ConvertString(const s: string): string; virtual; abstract; |
|
function ConvertChar(c: char): string; virtual; abstract; |
|
function CreateLink(const Item: TBaseItem): string; virtual; |
|
function CreateStream(const AName: string): Boolean; |
|
function ExtractEmailAddress(s: string; out S1, S2, EmailAddress: string): Boolean; |
|
function FixEmailaddressWithoutMailTo(const PossibleEmailAddress: String): String; |
|
function ExtractWebAddress(s: string; out S1, S2, WebAddress: string): Boolean; |
|
function FindGlobal(const NameParts: TNameParts): TBaseItem; |
|
function FindGlobalPasItem(const NameParts: TNameParts): TPasItem; overload; |
|
function FindGlobalPasItem(const ItemName: String): TPasItem; overload; |
|
function GetClassDirectiveName(Directive: TClassDirective): string; |
|
function GetCIOTypeName(MyType: TCIOType): string; |
|
procedure LoadDescriptionFile(n: string); |
|
function SearchItem(s: string; const Item: TBaseItem; WarningIfNotSplittable: boolean): TBaseItem; |
|
function SearchLink(s: string; const Item: TBaseItem; const LinkDisplay: string; const WarningIfLinkNotFound: boolean; out FoundItem: TBaseItem): string; overload; |
|
function SearchLink(s: string; const Item: TBaseItem; const LinkDisplay: string; const WarningIfLinkNotFound: boolean): string; overload; |
|
procedure StoreDescription(ItemName: string; var t: string); |
|
procedure WriteConverted(const s: string; Newline: boolean); overload; |
|
procedure WriteConverted(const s: string); overload; |
|
procedure WriteConvertedLine(const s: string); |
|
procedure WriteDirect(const t: string; Newline: boolean); overload; |
|
procedure WriteDirect(const t: string); overload; |
|
procedure WriteDirectLine(const t: string); |
|
procedure WriteUnit(const HL: integer; const U: TPasUnit); virtual; abstract; |
|
procedure WriteUnits(const HL: integer); |
|
procedure WriteStartOfCode; virtual; |
|
procedure WriteEndOfCode; virtual; |
|
procedure WriteGVUses; |
|
procedure WriteGVClasses; |
|
procedure StartSpellChecking(const AMode: string); |
|
procedure CheckString(const AString: string; const AErrors: TObjectVector); |
|
procedure EndSpellChecking; |
|
function FormatPascalCode(const Line: string): string; virtual; |
|
function FormatNormalCode(AString: string): string; virtual; |
|
function FormatComment(AString: string): string; virtual; |
|
function FormatHex(AString: string): string; virtual; |
|
function FormatNumeric(AString: string): string; virtual; |
|
function FormatFloat(AString: string): string; virtual; |
|
function FormatString(AString: string): string; virtual; |
|
function FormatKeyWord(AString: string): string; virtual; |
|
function FormatCompilerComment(AString: string): string; virtual; |
|
function Paragraph: string; virtual; |
|
function ShortDash: string; virtual; |
|
function EnDash: string; virtual; |
|
function EmDash: string; virtual; |
|
function HtmlString(const S: string): string; virtual; |
|
function LatexString(const S: string): string; virtual; |
|
function LineBreak: string; virtual; |
|
function URLLink(const URL: string): string; overload; virtual; |
|
function URLLink(const URL, LinkDisplay: string): string; overload; virtual; |
|
procedure WriteExternal(const ExternalItem: TExternalItem; const Id: TTranslationID); |
|
procedure WriteExternalCore(const ExternalItem: TExternalItem; const Id: TTranslationID); virtual; abstract; |
|
procedure WriteConclusion; |
|
procedure WriteIntroduction; |
|
procedure WriteAdditionalFiles; |
|
function FormatSection(HL: integer; const Anchor: string; const Caption: string): string; virtual; abstract; |
|
function FormatAnchor(const Anchor: string): string; virtual; abstract; |
|
function FormatBold(const Text: string): string; virtual; |
|
function FormatItalic(const Text: string): string; virtual; |
|
function FormatWarning(const Text: string): string; virtual; |
|
function FormatNote(const Text: string): string; virtual; |
|
function FormatPreformatted(const Text: string): string; virtual; |
|
function FormatImage(FileNames: TStringList): string; virtual; |
|
function FormatList(ListData: TListData): string; virtual; abstract; |
|
function FormatTable(Table: TTableData): string; virtual; abstract; |
|
function FormatTableOfContents(Sections: TStringPairVector): string; virtual; |
|
procedure BuildLinks; virtual; |
|
procedure ExpandDescriptions; |
|
function GetFileExtension: string; virtual; abstract; |
|
procedure LoadDescriptionFiles(const c: TStringVector); |
|
procedure WriteDocumentation; virtual; |
|
constructor Create(AOwner: TComponent); override; |
|
destructor Destroy; override; |
|
procedure ParseAbbreviationsFile(const AFileName: string); |
Properties
property CurrentStream: TStream read FCurrentStream; |
|
property Units: TPasUnits read FUnits write FUnits; |
|
property Introduction: TExternalItem read FIntroduction
write FIntroduction; |
|
property Conclusion: TExternalItem read FConclusion write FConclusion; |
|
property AdditionalFiles: TExternalItemList read FAdditionalFiles write FAdditionalFiles; |
|
property OnMessage: TPasDocMessageEvent read FOnMessage write FOnMessage; |
|
property Language: TLanguageID read GetLanguage write SetLanguage
default DEFAULT_LANGUAGE; |
|
property ProjectName: string read FProjectName write FProjectName; |
|
property ExcludeGenerator: Boolean
read FExcludeGenerator write FExcludeGenerator default false; |
|
property IncludeCreationTime: Boolean
read FIncludeCreationTime write FIncludeCreationTime default false; |
|
property UseLowercaseKeywords: Boolean
read FUseLowercaseKeywords write FUseLowercaseKeywords default false; |
|
property Title: string read FTitle write FTitle; |
|
property DestinationDirectory: string read FDestDir write SetDestDir; |
|
property OutputGraphVizUses: boolean read FGraphVizUses write FGraphVizUses
default false; |
|
property OutputGraphVizClassHierarchy: boolean
read FGraphVizClasses write FGraphVizClasses default false; |
|
property LinkGraphVizUses: string read FLinkGraphVizUses write FLinkGraphVizUses; |
|
property LinkGraphVizClasses: string read FLinkGraphVizClasses write FLinkGraphVizClasses; |
|
property Abbreviations: TStringList read FAbbreviations write SetAbbreviations; |
|
property CheckSpelling: boolean read FCheckSpelling write FCheckSpelling
default false; |
|
property AspellLanguage: string read FAspellLanguage write FAspellLanguage; |
|
property SpellCheckIgnoreWords: TStringList
read FSpellCheckIgnoreWords write SetSpellCheckIgnoreWords; |
|
property AutoAbstract: boolean read FAutoAbstract write FAutoAbstract default false; |
|
property LinkLook: TLinkLook read FLinkLook write FLinkLook default llDefault; |
|
property WriteUsesClause: boolean
read FWriteUsesClause write FWriteUsesClause default false; |
|
property AutoLink: boolean
read FAutoLink write FAutoLink default false; |
|
property AutoLinkExclude: TStringList read FAutoLinkExclude; |
|
property ExternalClassHierarchy: TStrings
read FExternalClassHierarchy write SetExternalClassHierarchy
stored StoredExternalClassHierarchy; |
|
property Markdown: boolean
read FMarkdown write FMarkdown default false; |
Description
Fields
FLanguage: TPasDocLanguages; |
|
the (human) output language of the documentation file(s) |
FClassHierarchy: TStringCardinalTree; |
|
FUnits: TPasUnits; |
|
list of all units that were successfully parsed |
Methods
procedure DoError(const AMessage: string; const AArguments: array of const; const AExitCode: Word); |
|
procedure DoMessage(const AVerbosity: Cardinal; const MessageType: TPasDocMessageType; const AMessage: string; const AArguments: array of const); |
|
procedure CreateClassHierarchy; |
|
function MakeItemLink(const Item: TBaseItem; const LinkCaption: string; const LinkContext: TLinkContext): string; virtual; |
|
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. |
procedure WriteCodeWithLinksCommon(const Item: TPasItem; const Code: string; WriteItemLink: boolean; const NameLinkBegin, NameLinkEnd: string); |
|
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. |
procedure CloseStream; |
|
If field CurrentStream is assigned, it is disposed and set to nil. |
function CreateLink(const Item: TBaseItem): string; virtual; |
|
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. |
function CreateStream(const AName: string): Boolean; |
|
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 |
function ExtractEmailAddress(s: string; out S1, S2, EmailAddress: string): Boolean; |
|
Searches for an email address in String S. Searches for first appearance of the @ character |
function ExtractWebAddress(s: string; out S1, S2, WebAddress: string): Boolean; |
|
Searches for a web address in String S. It must either contain a http:// or start with www. |
function FindGlobal(const NameParts: TNameParts): TBaseItem; |
|
Searches all items in all units (given by field Units) for item with NameParts. Returns a pointer to the item on success, nil otherwise. |
function FindGlobalPasItem(const NameParts: TNameParts): TPasItem; overload; |
|
Find a Pascal item, searching global namespace. Returns |
function FindGlobalPasItem(const ItemName: String): TPasItem; overload; |
|
Find a Pascal item, searching global namespace. Assumes that Name is only one component (not something with dots inside). Returns |
function GetClassDirectiveName(Directive: TClassDirective): string; |
|
|
function GetCIOTypeName(MyType: TCIOType): string; |
|
|
procedure LoadDescriptionFile(n: string); |
|
Loads descriptions from file N and replaces or fills the corresponding comment sections of items. |
function SearchItem(s: string; const Item: TBaseItem; WarningIfNotSplittable: boolean): TBaseItem; |
|
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. |
function SearchLink(s: string; const Item: TBaseItem; const LinkDisplay: string; const WarningIfLinkNotFound: boolean; out FoundItem: TBaseItem): string; overload; |
|
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 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
|
function SearchLink(s: string; const Item: TBaseItem; const LinkDisplay: string; const WarningIfLinkNotFound: boolean): string; overload; |
|
Just like previous overloaded version, but this doesn't return FoundItem (in case you don't need it). |
procedure StoreDescription(ItemName: string; var t: string); |
|
procedure WriteConverted(const s: string; Newline: boolean); overload; |
|
Writes S to CurrentStream, converting it using ConvertString. Then optionally writes LineEnding. |
procedure WriteConverted(const s: string); overload; |
|
Writes S to CurrentStream, converting it using ConvertString. No LineEnding at the end. |
procedure WriteConvertedLine(const s: string); |
|
Writes S to CurrentStream, converting it using ConvertString. Then writes LineEnding. |
procedure WriteDirect(const t: string; Newline: boolean); overload; |
|
Simply writes T to CurrentStream, with optional LineEnding. |
procedure WriteDirect(const t: string); overload; |
|
Simply writes T to CurrentStream. |
procedure WriteDirectLine(const t: string); |
|
Simply writes T followed by LineEnding to CurrentStream. |
procedure WriteUnit(const HL: integer; const U: TPasUnit); virtual; abstract; |
|
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. |
procedure WriteUnits(const HL: integer); |
|
Writes documentation for all units, calling WriteUnit for each unit. |
procedure WriteStartOfCode; virtual; |
|
procedure WriteEndOfCode; virtual; |
|
procedure WriteGVUses; |
|
output graphviz uses tree |
procedure WriteGVClasses; |
|
output graphviz class tree |
procedure StartSpellChecking(const AMode: string); |
|
starts the spell checker |
procedure CheckString(const AString: string; const AErrors: TObjectVector); |
|
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. |
procedure EndSpellChecking; |
|
closes the spellchecker |
function FormatNormalCode(AString: string): string; virtual; |
|
This will cause AString to be formatted in the way that normal Pascal statements (not keywords, strings, comments, etc.) look in Delphi. |
function FormatComment(AString: string): string; virtual; |
|
FormatComment will cause AString to be formatted in the way that comments other than compiler directives are formatted in Delphi. See: FormatCompilerComment. |
function FormatHex(AString: string): string; virtual; |
|
FormatHex will cause AString to be formatted in the way that Hex are formatted in Delphi. |
function FormatNumeric(AString: string): string; virtual; |
|
FormatNumeric will cause AString to be formatted in the way that Numeric are formatted in Delphi. |
function FormatFloat(AString: string): string; virtual; |
|
FormatFloat will cause AString to be formatted in the way that Float are formatted in Delphi. |
function FormatString(AString: string): string; virtual; |
|
FormatString will cause AString to be formatted in the way that strings are formatted in Delphi. |
function FormatKeyWord(AString: string): string; virtual; |
|
FormatKeyWord will cause AString to be formatted in the way that reserved words are formatted in Delphi. |
function FormatCompilerComment(AString: string): string; virtual; |
|
FormatCompilerComment will cause AString to be formatted in the way that compiler directives are formatted in Delphi. |
function Paragraph: string; virtual; |
|
This is paragraph marker in output documentation. Default implementation in this class simply returns ' ' (one space). |
function ShortDash: string; virtual; |
|
See TTagManager.ShortDash. Default implementation in this class returns '-'. |
function EnDash: string; virtual; |
|
See TTagManager.EnDash. Default implementation in this class returns '--'. |
function EmDash: string; virtual; |
|
See TTagManager.EmDash. Default implementation in this class returns '---'. |
function LatexString(const S: string): string; virtual; |
|
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". |
function URLLink(const URL: string): string; overload; virtual; |
|
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. |
procedure WriteExternal(const ExternalItem: TExternalItem; const Id: TTranslationID); |
|
|
procedure WriteExternalCore(const ExternalItem: TExternalItem; const Id: TTranslationID); virtual; abstract; |
|
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. |
procedure WriteConclusion; |
|
|
procedure WriteIntroduction; |
|
|
procedure WriteAdditionalFiles; |
|
|
function FormatSection(HL: integer; const Anchor: string; const Caption: string): string; virtual; abstract; |
|
|
function FormatAnchor(const Anchor: string): string; virtual; abstract; |
|
|
function FormatBold(const Text: string): string; virtual; |
|
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 See also
|
function FormatItalic(const Text: string): string; virtual; |
|
This returns Text formatted using italic font. Analogous to FormatBold. |
function FormatWarning(const Text: string): string; virtual; |
|
This returns Text using bold font by calling FormatBold(Text). |
function FormatNote(const Text: string): string; virtual; |
|
This returns Text using italic font by calling FormatItalic(Text). |
function FormatList(ListData: TListData): string; virtual; abstract; |
|
Format a list from given ListData. |
function FormatTable(Table: TTableData): string; virtual; abstract; |
|
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. |
function FormatTableOfContents(Sections: TStringPairVector): string; virtual; |
|
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. |
procedure BuildLinks; virtual; |
|
Creates anchors and links for all items in all units. |
procedure ExpandDescriptions; |
|
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. |
function GetFileExtension: string; virtual; abstract; |
|
Abstract function that provides file extension for documentation format. Must be overwritten by descendants. |
procedure LoadDescriptionFiles(const c: TStringVector); |
|
Assumes C contains file names as PString variables. Calls LoadDescriptionFile with each file name. |
constructor Create(AOwner: TComponent); override; |
|
destructor Destroy; override; |
|
procedure ParseAbbreviationsFile(const AFileName: string); |
|
Properties
property CurrentStream: TStream read FCurrentStream; |
|
property Units: TPasUnits read FUnits write FUnits; |
|
property Introduction: TExternalItem read FIntroduction
write FIntroduction; |
|
property Conclusion: TExternalItem read FConclusion write FConclusion; |
|
property AdditionalFiles: TExternalItemList read FAdditionalFiles write FAdditionalFiles; |
|
property OnMessage: TPasDocMessageEvent read FOnMessage write FOnMessage; |
|
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. |
property Language: TLanguageID read GetLanguage write SetLanguage
default DEFAULT_LANGUAGE; |
|
the (human) output language of the documentation file(s) |
property ProjectName: string read FProjectName write FProjectName; |
|
Name of the project to create. |
property ExcludeGenerator: Boolean
read FExcludeGenerator write FExcludeGenerator default false; |
|
"Generator info" are things that can change with each invocation of pasdoc, with different pasdoc binary etc. This includes
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). |
property IncludeCreationTime: Boolean
read FIncludeCreationTime write FIncludeCreationTime default false; |
|
Show creation time in the output. |
property UseLowercaseKeywords: Boolean
read FUseLowercaseKeywords write FUseLowercaseKeywords default false; |
|
Setting to define how literal tag keywords should appear in documentaion. |
property Title: string read FTitle write FTitle; |
|
Title of the documentation, supplied by user. May be empty. See TPasDoc.Title. |
property OutputGraphVizUses: boolean read FGraphVizUses write FGraphVizUses
default false; |
|
generate a GraphViz diagram for the units dependencies |
property OutputGraphVizClassHierarchy: boolean
read FGraphVizClasses write FGraphVizClasses default false; |
|
generate a GraphViz diagram for the Class hierarchy |
property LinkGraphVizUses: string read FLinkGraphVizUses write FLinkGraphVizUses; |
|
link the GraphViz uses diagram |
property LinkGraphVizClasses: string read FLinkGraphVizClasses write FLinkGraphVizClasses; |
|
link the GraphViz classes diagram |
property Abbreviations: TStringList read FAbbreviations write SetAbbreviations; |
|
property CheckSpelling: boolean read FCheckSpelling write FCheckSpelling
default false; |
|
property AspellLanguage: string read FAspellLanguage write FAspellLanguage; |
|
property SpellCheckIgnoreWords: TStringList
read FSpellCheckIgnoreWords write SetSpellCheckIgnoreWords; |
|
property AutoAbstract: boolean read FAutoAbstract write FAutoAbstract default false; |
|
The meaning of this is just like --auto-abstract command-line option. It is used in ExpandDescriptions. |
property LinkLook: TLinkLook read FLinkLook write FLinkLook default llDefault; |
|
This controls SearchLink behavior, as described in [https://github.com/pasdoc/pasdoc/wiki/LinkLookOption]. |
property WriteUsesClause: boolean
read FWriteUsesClause write FWriteUsesClause default false; |
|
property AutoLink: boolean
read FAutoLink write FAutoLink default false; |
|
This controls auto-linking, see [https://github.com/pasdoc/pasdoc/wiki/AutoLinkOption] |
property AutoLinkExclude: TStringList read FAutoLinkExclude; |
|
property ExternalClassHierarchy: TStrings
read FExternalClassHierarchy write SetExternalClassHierarchy
stored StoredExternalClassHierarchy; |
|
property Markdown: boolean
read FMarkdown write FMarkdown default false; |
|
Generated by PasDoc 0.16.0.