Class TTagManager

Description
Hierarchy
Methods
Properties

Unit

PasDoc_TagManager

Declaration

type TTagManager = class(TObject)

Description

This item has no description.

Source: source/component/PasDoc_TagManager.pas (line 316).

Hierarchy

Overview

Methods

Public constructor Create;
Public destructor Destroy; override;
Public procedure DoMessage(const AVerbosity: Cardinal; const MessageType: TPasDocMessageType; const AMessage: string; const AArguments: array of const);
Public procedure DoMessageNonPre(const AVerbosity: Cardinal; const MessageType: TPasDocMessageType; const AMessage: string; const AArguments: array of const);
Public function Execute(const Description: string; AutoLink: boolean; WantFirstSentenceEnd: boolean; out FirstSentenceEnd: Integer): string; overload;
Public function Execute(const Description: string; AutoLink: boolean): string; overload;
Public function CoreExecute(const Description: string; AutoLink: boolean; EnclosingTag: TTag; var EnclosingTagData: TObject; WantFirstSentenceEnd: boolean; out FirstSentenceEnd: Integer): string; overload;
Public function CoreExecute(const Description: string; AutoLink: boolean; EnclosingTag: TTag; var EnclosingTagData: TObject): string; overload;

Properties

Public property OnMessage: TPasDocMessageEvent read FOnMessage write FOnMessage;
Public property Paragraph: string read FParagraph write FParagraph;
Public property Space: string read FSpace write FSpace;
Public property ShortDash: string read FShortDash write FShortDash;
Public property EnDash: string read FEnDash write FEnDash;
Public property EmDash: string read FEmDash write FEmDash;
Public property URLLink: TStringConverter read FURLLink write FURLLink;
Public property OnTryAutoLink: TTryAutoLinkEvent read FOnTryAutoLink write FOnTryAutoLink;
Public property ConvertString: TStringConverter read FConvertString write FConvertString;
Public property Abbreviations: TStringList read FAbbreviations write FAbbreviations;
Public property PreExecute: boolean read FPreExecute write FPreExecute;
Public property Markdown: boolean read FMarkdown write FMarkdown default false;

Description

Methods

Public constructor Create;

This item has no description.

Source: source/component/PasDoc_TagManager.pas (line 337).

Public destructor Destroy; override;

This item has no description.

Source: source/component/PasDoc_TagManager.pas (line 338).

Public procedure DoMessage(const AVerbosity: Cardinal; const MessageType: TPasDocMessageType; const AMessage: string; const AArguments: array of const);

Call OnMessage (if assigned) with given params.

Source: source/component/PasDoc_TagManager.pas (line 341).

Public procedure DoMessageNonPre(const AVerbosity: Cardinal; const MessageType: TPasDocMessageType; const AMessage: string; const AArguments: array of const);

Call DoMessage only if PreExecute is False.

Source: source/component/PasDoc_TagManager.pas (line 346).

Public function Execute(const Description: string; AutoLink: boolean; WantFirstSentenceEnd: boolean; out FirstSentenceEnd: Integer): string; overload;

This method is the very essence of this class and this unit. It expands Description, which means that it processes Description (text supplied by user in some comment in parsed unit) into something ready to be included in output documentation. This means that this handles parsing @-tags, inserting paragraph markers, recognizing URLs in Description and correctly translating it, and translating rest of the "normal" text via ConvertString.

If WantFirstSentenceEnd then we will look for '.' char followed by any whitespace in Description. Moreover, this '.' must be outside of any @-tags parameter. Under FirstSentenceEnd we will return the number of beginning characters in the output string that will include correspong '.' character (note that this definition takes into account that ConvertString may translate '.' into something longer). If no such character exists in Description, FirstSentenceEnd will be set to Length(Result), so the whole Description will be treated as it's first sentence.

If WantFirstSentenceEnd, FirstSentenceEnd will not be set.

Source: source/component/PasDoc_TagManager.pas (line 450).

Public function Execute(const Description: string; AutoLink: boolean): string; overload;

This is equivalent to Execute(Description, AutoLink, false, Dummy)

Source: source/component/PasDoc_TagManager.pas (line 456).

Public function CoreExecute(const Description: string; AutoLink: boolean; EnclosingTag: TTag; var EnclosingTagData: TObject; WantFirstSentenceEnd: boolean; out FirstSentenceEnd: Integer): string; overload;

This is the underlying version of Execute. Use with caution!

If EnclosingTag = nil then this is understood to be toplevel of description, which means that all tags are allowed inside.

If EnclosingTag <> nil then this is not toplevel.

EnclosingTagData returns collected data for given EnclosingTag. You should init it to EnclosingTag.CreateOccurenceData. It will be passed as EnclosingTagData to each of @-tags found inside Description.

Source: source/component/PasDoc_TagManager.pas (line 470).

Public function CoreExecute(const Description: string; AutoLink: boolean; EnclosingTag: TTag; var EnclosingTagData: TObject): string; overload;

This item has no description.

Source: source/component/PasDoc_TagManager.pas (line 476).

Properties

Public property OnMessage: TPasDocMessageEvent read FOnMessage write FOnMessage;

This will be used to print messages from within Execute.

Note that in this unit we essentialy "don't know" that parsed Description string is probably attached to some TPasItem. It's good that we don't know it (because it makes this class more flexible). But it also means that OnMessage that you assign here may want to add to passed AMessage something like + ' (Expanded_TPasItem_Name)', see e.g. TDocGenerator.DoMessageFromExpandDescription. Maybe in the future we will do some descendant of this class, like TTagManagerForPasItem.

Source: source/component/PasDoc_TagManager.pas (line 360).

Public property Paragraph: string read FParagraph write FParagraph;

This will be inserted on paragraph marker (two consecutive newlines, see wiki page WritingDocumentation) in the text. This should specify how paragraphs are marked in particular output format, e.g. html generator may set this to '<p>'.

Default value is ' ' (one space).

Source: source/component/PasDoc_TagManager.pas (line 368).

Public property Space: string read FSpace write FSpace;

This will be inserted on each whitespace sequence (but not on paragraph break). This is consistent with WritingDocumentation that clearly says that "amount of whitespace does not matter".

Although in some pasdoc output formats amount of whitespace also does not matter (e.g. HTML and LaTeX) but in other (e.g. plain text) it matters, so such space compression is needed. In other output formats (no examples yet) it may need to be expressed by something else than simple space, that's why this property is exposed.

Default value is ' ' (one space).

Source: source/component/PasDoc_TagManager.pas (line 383).

Public property ShortDash: string read FShortDash write FShortDash;

This will be inserted on @- in description, and on a normal single dash in description that is not a part of en-dash or em-dash. This should produce just a short dash.

Default value is '-'.

You will never get any '-' character to be converted by ConvertString. Convertion of '-' is controlled solely by XxxDash properties of tag manager.

See also
EnDash
This will be inserted on -- in description.
EmDash
This will be inserted on --- in description.

Source: source/component/PasDoc_TagManager.pas (line 398).

Public property EnDash: string read FEnDash write FEnDash;

This will be inserted on -- in description. This should produce en-dash (as in LaTeX). Default value is '--'.

Source: source/component/PasDoc_TagManager.pas (line 403).

Public property EmDash: string read FEmDash write FEmDash;

This will be inserted on --- in description. This should produce em-dash (as in LaTeX). Default value is '---'.

Source: source/component/PasDoc_TagManager.pas (line 408).

Public property URLLink: TStringConverter read FURLLink write FURLLink;

This will be called from Execute when URL will be found in Description. Note that passed here URL will not be processed by ConvertString.

This tells what to put in result on URL. If this is not assigned, then ConvertString(URL) will be appended to Result in Execute.

Source: source/component/PasDoc_TagManager.pas (line 417).

Public property OnTryAutoLink: TTryAutoLinkEvent read FOnTryAutoLink write FOnTryAutoLink;

This should check does QualifiedIdentifier looks like a name of some existing identifier. If yes, sets AutoLinked to true and sets QualifiedIdentifierReplacement to a link to QualifiedIdentifier (QualifiedIdentifierReplacement should be ready to be put in final documentation, i.e. already in the final output format). By default AutoLinked is false.

Source: source/component/PasDoc_TagManager.pas (line 425).

Public property ConvertString: TStringConverter read FConvertString write FConvertString;

This item has no description.

Source: source/component/PasDoc_TagManager.pas (line 480).

Public property Abbreviations: TStringList read FAbbreviations write FAbbreviations;

This item has no description.

Source: source/component/PasDoc_TagManager.pas (line 482).

Public property PreExecute: boolean read FPreExecute write FPreExecute;

When PreExecute is True, tag manager will work a little differently than usual:

  • Instead of TTag.Execute, TTag.PreExecute will be called.

  • Various warnings will not be reported.

    Assumption is that you will later process the same text with PreExecute set to False to get all the warnings.

  • AutoLink will not be used (like it was always false). Also the result of Execute will be pretty much random and meaningless (so you should ignore it). Also this means that the TagParameter for tags with toRecursiveTags should be ignored, because it will be something incorrect. This means that only tags without toRecursiveTags should actually use TagParameter in their OnPreExecute handlers.

    Assumption is that you actually don't care about the result of Execute methods, and you will later process the same text with PreExecute set to False to get the proper output.

    The goal is to make execution with PreExecute set to True as fast as possible.

Source: source/component/PasDoc_TagManager.pas (line 512).

Public property Markdown: boolean read FMarkdown write FMarkdown default false;

When Markdown is True, Markdown syntax is considered

Source: source/component/PasDoc_TagManager.pas (line 516).

Generated by PasDoc 0.17.0.snapshot.