ucommentdoc.pas

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

  //Type of documentation to inherit with an ~[code ~~~[[inheritDoc~[]]
  //command in a comment. Depends on the section the command appears in.
  TInheritedDocSection = (
                          //no valid section to inherit the comment from
                          idsInvalid,
                          //inherit the main comment at the beginning
                          idsText,
                          //inherit the comment of a parameter
                          idsParam,
                          //inherit the comment of the result of a function
                          idsResult);






  {The messages that can be generated by the generators in the class
   ~[link TCommentDoc]. }
  TCommentDocMessageKind = (
                            //the identifier to create a link to wasn't found
                            cdmkUnknownLinkTarget,
                            //the index of the overloaded function to link to
                            //is invalid or negative
                            cdmkInvalidOverloadedFunctionIndex,
                            //link to a field (starting with .) outside of a
                            //record-like type
                            cdmkInRecordLinkOutsideRecord,
                            //index of overloaded function specified in link
                            //target, but the identifier is not a function
                            cdmkIdentifierNotAFunctionButLinkWithIndex,
                            //not enough overloaded functions defined in
                            //context for the index
                            cdmkNotEnoughOverloadedFunctionsForIndex,

                            //no identifier to inherit documentation from;
                            //probably erroneous usage of ~~[inheritdoc]
                            cdmkNoAncestorWithDocumentation,
                            //invalid position for inline command
                            //~~[inheritdoc]
                            cdmkInvalidPositionForInheritanceOfDocumentation,
                            //found an identifier of an invalid kind while
                            //searching for identifier to inherit documentation
                            //from (can possibly be ignored)
                            cdmkInvalidIdentWhileSearchingAncestorIdent,

                            //an invalid section in a comment has been
                            //encountered; possible [] or the quoting of ~~ has
                            //been forgotten
                            cdmkUnknownSection,

                            //help context don't match, i.e. it has already
                            //been used for another topic or the topic already
                            //has another help context
                            cdmkHelpContextMismatch,

                            //a page with the same name exists already;
                            //section: ~~page
                            cdmkUserDocPageNameNotUnique
                           );








  {The abstract base-class of all generators of documentation that parse the
   comments in the source code. To generate several lists and comments the also
   abstract sub-class ~[linkClass UFormatCommentDoc.TFormatCommentDoc] is
   available, so this class is only directly subclassed by that class.

   Several functions for parsing and handling comments and the sections and
   inline commands in the comments are declared. Abstract methods to format the
   texts are introduced.
   
   The extraction of the comments are done by a descendant of
   ~[link TCommentExtractor]. All comments to be included in the documentation
   are returned by it, so far only one real class exists, ~[link
   USourceCommentExtraction.TSourceCommentExtractor], that extracts the
   comments from the source code at and above the declaration of the
   identifiers.~[br]
   These comments are evaluated by a descendant of
   ~[link TCommentEvaluator]. In the simplest version the texts are just
   returned as they are, just formatted in the format of the generator. But
   again, only on class exists, in this case
   ~[link UInlineCommand.TJADDCommentEvaluator], that will evaluate inline
   commands like used in JADD and you can see in exact this comment. }
  TCommentDoc = class(TDocumentDoc)
  private
    //ID of the messages of this class
    FCommentDocMessagesID: TMessageID;


    //insert a ~~[br] at the end of each line
    FKeepLineBreaksInComments: Boolean;

    //if the list of parameters of functions should be generated even if no
    FParameterListIfUncommented: Boolean;         //parameter is commented
    //if the result of a function should be listed even if it is not commented
    FResultIfUncommented: Boolean;
    //filter sections in the comments
    FFilterCommentSections: TIgnoreCommentSections;



    //the object to evaluate possible inline commands in the comments
    FEvaluator: TCommentEvaluator;


    //the reader of the data of the GUI to generate documentation about
    FGUIHelpReader: TGUIHelpReader;


    //if currently user documentation is parsed/generated
    FInUserDoc: Boolean;
    //number of the current page in the user documentation
    FCurrentUserDocPage: Integer;
    //the currently read file of user documentation
    FReadUserDocCurrentFile: Integer;
    //the list of already parsed files of user documentation; the objects are
    //integers - the highest page number belonging to the parsed file
    FReadUserDocFiles: TStringList;

    //the list of the names of the pages (can be used for links)
    FUserDocPages: TStringList;
    //the content of the pages of used documentation
    FUserDocPageContents: TStringList;
    //the text for the index of the user documentation; assembled from all read
    //files of user documentation before the first ~~page-section
    FUserDocIndexText: String;



    //list of links inside the current image;
    //items are of type ~[link TImageLinkData]
    FImageLinks: TImageLinkList;



    //the identifier the comment is read and parsed of
    FCommentIdent: TIdentifier;
    //the file the comment is read and parsed of
    FCommentFile: TPascalFile;

    //the identifier for that the current documentation is generated and a link
    //from may be needed; this may be different from ~[link FCommentIdent] in
    //case of inheriting some documentation by ~[code ~~~[[inheritDoc~[]]; only
    //used in ~[linkClass UHTMLDoc.THTMLDoc] for local links (in same file)
    FLinkIdent: TIdentifier;
    //the file of the identifier documentation is being generated of
    FLinkFile: TPascalFile;


    //the help context of the current topic, only relevant in Window Help files
    //and HTML Help files
    FCurrentHelpContext: Cardinal;




    //the list of registered help contexts;
    //the text is the topic, the object is the context number
    FHelpContextList: TStringList;






    //Returns whether raw line breaks should be kept within the comment.
    function GetKeepRawLineBreaks: Boolean;





  protected

    //section of a comment to inherit by ~[code ~~~[[inheritDoc~[]]
    FInheritedDocSection: TInheritedDocSection;
    //the parameter for that a comment is currently parsed; used in case of
    //~[code ~~~[[inheritDoc~[]] in the comment of a parameter;
    //i.e. ~[link FInheritedDocSection] is ~[link idsParam]
    FCurrentDocParameter: TParameter;





    //the list of deprecated identifiers (only the ones tagged in their comment
    //by ~~deprecated)
    FDeprecatedList: TIdentifierFileList;
    //the list of unfinished identifiers (tagged in their comment by ~~todo)
    FTODOList: TIdentifierFileList;
    //the list of feature-missing identifiers (tagged in their comment by
    //~~feature)
    FFeatureList: TIdentifierFileList;




    //Sets the identifier of which the documentation is generated.
    procedure SetCommentIdent(CommentIdent: TIdentifier;
                              CommentFile: TPascalFile;
                              SetLink: Boolean = True);
    //Sets the identifier from whose documentation links should be generated.
    procedure SetLinkIdent(LinkIdent: TIdentifier; LinkFile: TPascalFile);
    //Returns a string representing the current identifier to generate
    //documentation about.
    function GetCurrentCommentPosition: String;
    //Sets the current position in the message.
    procedure SetCurrentPosition(var Message: TGeneratorMessage);








    //Parses the comment to a text in the format of the documentation.
    function ParseCommentText(const Text: String): String;






    //Returns the comment on the current identifier or file.
    function GetComment: TComment;


    //Inherits the main comment of the property from its field/method to read.
    function GetPropertyMainComment: String;





    //If a help context was defined the topic it is mapped accordingly.
    procedure CheckHelpContext(const TopicName: String);








    //Returns the content and title of a page of the user documentation.
    function GetUserDocumentationPage(Page: Integer;
                                      var Title: String): String;
    {Writes the current page of the user documentation. Will be called by
     ~[link CreateUserDocumentation] for each page. }
    procedure CreateUserDocPage; virtual; abstract;
    //Write the user documentation and returns if there was something to write.
    function CreateUserDocumentation: Boolean;
    //Returns if user documentation is available and should be written.
    function UserDocumentationAvailable: Boolean;




    //Adds an additional file of user documentation to include.
    procedure AddUserDocFile(const FileName: String);

    {Generate only the user documentation.
    ~result if the documentation has been successfully generated and generation
            hasn't been aborted }
    function DoGenerateOnlyUserDocumentation: Boolean; virtual; abstract;

    //Generate the help on a GUI.
    function DoGenerateGUIHelp(LogFiles: TStrings): Boolean; virtual;




    //Decides how to generate the documentation.
    function GenerateDocumentationWith(const Info:
                                              TGenerationInformation): Boolean;
                                                                      override;



    property CommentDocMessagesID: TMessageID read FCommentDocMessagesID;


    property ParameterListIfUncommented: Boolean
                                              read FParameterListIfUncommented;
    property ResultIfUncommented: Boolean read FResultIfUncommented;
    property FilterCommentSections: TIgnoreCommentSections
                                                   read FFilterCommentSections;


                                                   
    property InUserDoc: Boolean read FInUserDoc;
    property CurrentUserDocPage: Integer read FCurrentUserDocPage;
    property UserDocIndexText: String read FUserDocIndexText;

    property KeepRawLineBreaks: Boolean read GetKeepRawLineBreaks;


    property LinkIdent: TIdentifier read FLinkIdent;
    property LinkFile: TPascalFile read FLinkFile;

  public
    //Creates the generator object.
    constructor Create; override;
    //Destroys the generator object.
    destructor Destroy; override;


    //Returns the capabilities of this class of the generators.
    class function Capabilities: TGeneratorCapabilities; override;



    //Returns the number of available options in generators of this class.
    class function GetOptionCount: Cardinal; override;
    //Gets a description of an option.
    class procedure GetOptionDescription(Index: Cardinal;
                                         var Desc: TOptionDescription);
                                                                      override;
    //Gets the value of an option.
    function GetOption(Index: Cardinal): TOptionValue; override;
    //Sets the value of an option.
    procedure SetOption(Index: Cardinal; const Value: TOptionValue); override;

    //Adds all wrappers for all options of the different objects to the list.
    procedure AddOptionWrappers(const List: TOptionWrapperList); override;



    //Handles text of the comment by encoding special characters of the format.
    function HandleRawCommentText(const Text: String): String; virtual;



    {Returns the text in the format; text may already include other formats.
    ~param TextFormat      the format the text should be in
    ~param Text            the text to format
    ~param SkipWhitespaces out: if following white spaces should be
                                skipped/ignored
    ~result the formatted text }
    function FormatText(TextFormat: TDocumentationTextFormat;
                        const Text: String;
                        var SkipWhitespaces: Boolean): String; virtual;
                                                               abstract;
    {Forces a new line or paragraph to start, i.e. breaks the current line or
     paragraph.
    ~param InsertParagraph if a paragraph break should be returned instead of a
                           line break
    ~param SkipWhitespaces out: if following white spaces should be
                                skipped/ignored
    ~result the line or paragraph break }
    function LineParagraphBreak(InsertParagraph: Boolean;
                                var SkipWhitespaces: Boolean): String; virtual;
                                                                      abstract;


    //Generates a warning for every residual section in a comment.
    procedure CheckInvalidSections(Comment: TComment);

    //Gets the (internal) identification (for links) of a topic of
    //documentation of a GUI.
    function GetGUIHelpURIByIndex(FileIndex, TopicIndex: Integer): String;
                                                                       virtual;
    //Gets the position (for links) of a topic of documentation of a GUI.
    function GetGUIHelpPosition(Target: String;
                                var Index: Integer): TOldGUIHelpData;
    //Gets the (internal) identification (for links) of a topic of
    //documentation of a GUI.
    function GetGUIHelpURI(Target: String): String;
    //Gets the (internal) index of a page in the user documentation.
    function GetPageIndex(const PageName: String): Integer;