uiccommentdoc.pas

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

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2003-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}


unit UICCommentDoc;

{Contains the abstract base-class of all generators of documentation that parse
 the comments in the source code to an intermediary ~[linkUnit UICNodes COM] -
 Commment Object Model: ~[linkClass TICCommentDoc]. All generators of this
 kind will subclass it.
}

interface

uses Windows, Classes, Graphics, 
     UBaseIdents,
     UOptions, UGenerationMessages, UGUIHelpIndexContent, UImages, 
     UMakeDoc, UICDocumentDoc,
     UICNodes, UILComment, UICGUIHelpData,
     UICIdentDocBuilder,
     UCommentScanner;




type


   { * * *  ***  * * *  ***   TICCommentDoc   ***  * * *  ***  * * *  }


  //type to filter some sections of the documentation (mostly lists)
  TDocumentationSectionsFilter = (
                                  //don't generate list of deprecated
                                  dsfDeprecated,            //identifiers
                                  //don't generate list of library-specific
                                  dsfLibrary,               //identifiers
                                  //don't generate list of platform-specific
                                  dsfPlatform,              //identifiers
                                  //don't generate list of unfinished
                                  dsfToDo,                  //identifiers
                                  //don't generate list of identifiers missing
                                  dsfFeature,               //a feature
                                  //don't generate list of all exported
                                  dsfExporteds,             //identifiers
                                  //don't generate list of long functions
                                  dsfLongFunctions,
                                  //don't generate index of all identifiers and
                                  dsfIndex,                 //files
                                  //don't generate a legend of used symbols in
                                  dsfLegend);               //the documentation

  //type to filter some sections of the documentation (mostly lists)
  TDocumentationSectionsFilters = set of TDocumentationSectionsFilter;




  {The messages that can be generated by the generators in the class
   ~[link TICCommentDoc]. }
  TICCommentDocMessageKind = (
                            //the identifier to create a link to wasn't found
                            cdmkUnknownLinkTarget,
                            //the identifier to create a link to wasn't found
                            //while generating the content of the main index
                            cdmkUnknownLinkTargetInMainIndex,
                            //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,

                            //a diagram to be inserted in the documentation is
                            //empty, no valid classes or files have been added
                            cdmkDiagramIsEmpty,

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

                            //the log file of the GUI is invalid
                            cdmkGUILogFileInvalid
                           );








  {The abstract base-class of all generators of documentation that parse the
   comments in the source code to an intermediary ~[linkUnit UICNodes COM] -
   Commment Object Model.~[br]
   This is done by the method ~[link PrepareCommentsForDocumentation] which
   uses the ~[link FCommentScanner] to obtain all comments.~[br]
   Methods for additional documentation, like lists of special
   identifiers, the user documentation or to generate a help on a GUI, are
   introduced. Several of them are abstract or at least virtual.

   For the extraction of comments a descendant of ~[link TCommentExtractor]
   is used by the scanner as it is available in the inherited property
   ~[link Extractor] from ~[linkClass TMakeDoc].

   The final comments are saved in an object of the class
   ~[linkClass TICSourceComments] in the field ~[link FComments]. Then these
   comments are restructured and merged by ~[linkClass TICIdentDocBuilder] to
   the documentation for each identifier and file. It will include the
   declaration of the identifier as assembled by
   ~[linkClass TICDeclarationAssembler]. }
  TICCommentDoc = class(TICDocumentDoc)
  private
    //ID of the messages of this class
    FICCommentDocMessagesID: TMessageID;

    //the object to scan the comments and transform them into the
    //~[linkUnit UICNodes COM]
    FCommentScanner: TCommentScanner;
    //builds the documentation of each identifier and file from their comments,
    //declaration and other information
    FDocumentationBuilder: TICIdentDocBuilder;

    //the comments of all identifiers and files
    FComments: TICSourceComments;
    //the pages of the additional user documentation
    FUserComments: TICUserDocComments;
    //the list of the data of the GUI to generate documentation about
    FGUIHelpData: TICGUIHelpList;

    //the alternative content for the main index;
    //if nil the normal content should be used
    FMainIndexContent: TICNList;



    //insert a ~~[br] at the end of each line
    FKeepLineBreaksInComments: Boolean;
    //filter some sections of the documentation (mostly lists)
    FDocumentationSectionsFilter: TDocumentationSectionsFilters;
    //whether the headings of the help topics instead of the internal component
    //names should be used as key words for the generated documentation as a
    //help on a GUI
    FGUIHelpUseTopicAsKeyWords: Boolean;


    //whether the final comments/the documentation should only be generated
    //when they are needed, and not all when starting the generation
    FGenerateDocumentationOnDemand: Boolean;




    //whether currently the comments are being prepared
    FInCommentPreparation: Boolean;
    //number of the current page in the user documentation
    FCurrentUserDocPage: Integer;

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



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



  protected
    //list of special(ly tagged) identifiers to be listed in the documentation;
    //this is a temporal field and it is not freed when the object is destroyed
    FSpecialIdentifiersList: TIdentifierFileList;


    //Sets the identifier of which the documentation is generated.
    procedure SetCommentIdent(CommentIdent: TIdentifier;
                              CommentFile: TPascalFile);
    //Assigns the current position.
    procedure AssignCurrentPosition(var Position: TDocumentationPosition);


    //Called for every comment belonging to an identifier (or file), adds it to
    //the list of special identifiers if it is deprecated.
    procedure AddDeprecatedIdentifiers(Comment: TICIdentifierComment;
                                       Identifier: TIdentifier;
                                       TheFile: TPascalFile;
                                       Sender: TICSourceComments);
    //Called for every comment belonging to an identifier (or file), adds it to
    //the list of special identifiers if it is unfinished.
    procedure AddUnfinishedIdentifiers(Comment: TICIdentifierComment;
                                       Identifier: TIdentifier;
                                       TheFile: TPascalFile;
                                       Sender: TICSourceComments);
    //Called for every comment belonging to an identifier (or file), adds it to
    //the list of special identifiers if it is missing a feature.
    procedure AddFeatureMissingIdentifiers(Comment: TICIdentifierComment;
                                           Identifier: TIdentifier;
                                           TheFile: TPascalFile;
                                           Sender: TICSourceComments);








     //Transforms the entries for the main index into a COM.
     procedure CreateCOMFromEntries(EntryRoot: TGUIMainIndexEntry;
                                    Destination: TICNList);





    {Writes the current page of the user documentation. Will be called by
     ~[link CreateUserDocumentation] for each page. }
    procedure CreateUserDocPage; virtual; abstract;
    //Writes the user documentation and returns whether there was something to
    //be written.
    function CreateUserDocumentation: Boolean;
    //Returns whether user documentation is available and should be written.
    function UserDocumentationAvailable: Boolean;




    //Clears a keyword off all special characters.
    function ClearAsKeyWords(const KeyWord: String): String;


    //Has to be overridden to generate the help on one data set of a GUI.
    procedure GenerateGUIHelpOnData(Data: TICGUIHelpData;
                                    AddContentTo: TICNCompound); virtual;
    //Generates the help on the GUI with all data.
    procedure GenerateGUIHelpDatas(AddContentTo: TICNCompound);


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

    //Generates the help on a GUI. Only valid if ~[link gcGUIHelp] in
    //~[link Capabilities].
    function DoGenerateGUIHelp: Boolean; virtual;



    //Returns the final comment of a file, has to be
    //~[link ReleaseFinalComment released] after that.
    function GetFinalFileComment(OfFile: TPascalFile): TICSimpleComment;
    //Returns the final comment of an identifier, has to be
    //~[link ReleaseFinalComment released] after that.
    function GetFinalIdentifierComment(Identifier: TIdentifier):
                                                              TICSimpleComment;
    //Releases a comment after being requested via ~[link GetFinalFileComment]
    //or ~[link GetFinalIdentifierComment].
    procedure ReleaseFinalComment(Comment: TICSimpleComment);



    //Generates the internal representation of the documentation for the
    //identifier or file.
    procedure GenerateIdentifierDocumentation(Comment: TICIdentifierComment;
                                              Identifier: TIdentifier;
                                              TheFile: TPascalFile;
                                              Sender: TICSourceComments);

    //Reads and transforms the comments of all identifiers and files and builds
    //their documentation in the internal representation.
    procedure PrepareCommentsForDocumentation(UserDocumentationFiles,
                                              GUIHelpLogFiles: TStrings);



    //Lets generators initialize themselves before comments are prepared.
    procedure BeforeCommentPreparation(GenerationKind: TDocGenerationKind);
                                                                       virtual;

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





    property GUIHelpUseTopicAsKeyWords: Boolean
                                               read FGUIHelpUseTopicAsKeyWords;
    property GenerateDocumentationOnDemand: Boolean
                                           read FGenerateDocumentationOnDemand;

    property MainIndexContent: TICNList read FMainIndexContent;

    property CurrentUserDocPage: Integer read FCurrentUserDocPage;

    property DocumentationSectionsFilter: TDocumentationSectionsFilters
                                             read FDocumentationSectionsFilter;
  public
    //Creates the generator object.
    constructor Create; override;
    //Destroys the generator object.
    destructor Destroy; 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;