uformatcommentdoc.pas

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

  TFileSectionsFilter = (
                         //don't list the units used by the file
                         fsfUsesUnits,
                         //don't list the files using this unit
                         fsfUsedBy,
                         //don't list the units included in this package
                         fsfRequires,
                         //don't list the identifiers exported in/by this file
                         fsfExporteds,
                         //don't show the parameters of the program (they are
                         //not used anymore)
                         fsfProgramParameters);


  //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. This type contains all
   types of messages for all (so far known) generators. }
  TFormatCommentDocMessageKind = (
                                  //a parameter has been commented more than
                                  //once
                                  fcdmkParamCommentedTwice,
                                  //an unknown parameter hab been commented
                                  fcdmkUnknownParamCommented,
                                  //parameter wasn't commented
                                  fcdmkParamNotCommented,
                                  //the result of function wasn't commented
                                  fcdmkResultNotCommented,

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







  {The abstract base-class of all generators of documentation that generates
   several specific lists and information. It serves mainly handy methods to be
   called by the descendant generator classes. All generators of documentation
   subclass it. }
  TFormatCommentDoc = class(TCommentDoc)
  private
    //ID of the messages of this class
    FFormatCommentDocMessagesID: TMessageID;


    //filter some sections of the documentation of an identifier
    FIdentifierSectionsFilter: set of TIdentifierSectionsFilter;
    //filter some sections of the documentation of a file
    FFileSectionsFilter: set of TFileSectionsFilter;
    //filter some sections of the documentation (mostly lists)
    FDocumentationSectionsFilter: TDocumentationSectionsFilters;


    //minimum number of lines the length of a function has to exceed to include
    //the function in the list of long functions
    FMinLongFunctionLines: Integer;

    //if unknown sections should be checked to contain the comments of
    FParamNamesAsSections: Boolean;         //parameters of a function



  protected
    //the string of a new line, by default #13#10, but may also be #10
    FNewLine: String;
    //strings used to format text in the documentation
    FFormatSettings: TFormatSettings;
    //strings used to start new lines and paragraphsin the documentation
    FLineParagraphBreak: TLineBreakParagraph;
    //strings used to generate formatted documentation
    FCommentFormats: TFormatStrings;









    //Parses the ~~see and ~~seeText sections of comments and returns their
    //documentation.
    function ParseSeeComment(Comment: TComment): String;
    //Parses the ~~author and ~~version sections of comments and returns their
    //documentation.
    function ParseAuthorVersionAdditionals(Comment: TComment): String;
    //Returns the documentation of examples in comments.
    function ParseExampleComment(Comment: TComment;
                                 var HeaderLinks: String): String; virtual;


    //Parses the ~~deprecated, ~~todo and ~~feature sections of comments and
    //returns their documentation.
    function GetSpecials(Comment: TComment): String;







    //Returns the documentation extracted from the comment of the file.
    function GetFileComment(var HeaderLinks: String): String;
    //Returns the documentation with all known data of the identifier.
    function GetIdentComment(var HeaderLinks: String): String;



    {Returns the format needed to express the scope (as an icon).
    ~param Scope the scope to show
    ~result the format to express the scope }
    function GetScope(Scope: TScope): String; virtual; abstract;
    {Returns the format needed to express the portability issues (as icons).
    ~param Issues the portability issues to show (may be the empty set)
    ~result the format to express the portability issues }
    function GetPortabilityIssues(Issues: TIdentPortabilities): String;
                                                             virtual; abstract;


    //Returns a list of the identifiers as part of the documentation.
    function CreateDocumentationList(List: TIdentifierList): String;
    //Gets the list of global identifiers used in the current function.
    function GetFuncGlobalsString: String;
    //Gets the list of all identifiers using the current identifier.
    function GetUsedByString: String;

    //Gets the lists of files using this file.
    function GetUsingFiles(AFile: TPascalFile): String;






    {Starts a list of exported identifiers and gets the formats to be inserted
     inside the list/table.
    ~param TheFile  the file to write the list to (can be opened here)
    ~param AFile    the file whose exported identifiers are listed; nil for all
                    exported identifiers
    ~param PreFirst if it is before the first file instead of the global list
    ~param First    the text before an entry is returned with this parameter
    ~param Second   the text between the identifier and the export index is
                    returned with this parameter; ignored if in a file list
    ~param Third    the text between the export index and the export name is
                    returned with this parameter; ignored if in a file list
    ~param Fourth   the text between the export name and the "resident"
                    directive is returned with this parameter; ignored if in a
                    file list
    ~param Fifth    the text between the "resident" directive and and the file
                    exporting is returned with this parameter; ignored if in a
                    file list
    ~param Sixth    the last entry after the file is returned with this
                    parameter }
    procedure StartExportsLists(var TheFile: TextFile; AFile: TPascalFile;
                                PreFirst: Boolean;
                                var First, Second, Third, Fourth, Fifth,
                                    Sixth: String); virtual; abstract;


    {Ends a list of exported identifiers.
    ~param TheFile  the file the list has been written to (can be closed here)
    ~param AFile    the file whose exported identifiers are listed; nil for all
                    exported identifiers
    ~param PostLast after the last file instead of the global list }
    procedure EndExportsLists(var TheFile: TextFile; AFile: TPascalFile;
                              PostLast: Boolean); virtual; abstract;
    //Writes the lists of all exported identifiers.
    function WriteExportsList(var DestFile: TextFile): Boolean;






    {Starts the list of long functions and gets the formats to be inserted
     inside the list.
    ~param TheFile the file to write the list to (can be opened here)
    ~param Pre     out: the text before an entry is returned with this
                        parameter
    ~param Middle  out: the text is an entry between the number of lines and
                        the link to the function is returned with this
                        parameter
    ~param Post    out: the text after an entry is returned with this
                        parameter }
    procedure StartLongFunctionsLists(var TheFile: TextFile;
                                      var Pre, Middle, Post: String); virtual;
                                                                      abstract;
    {Ends the list of long functions.
    ~param TheFile the file the list has been written to (can be closed here) }
    procedure EndLongFunctionsLists(var TheFile: TextFile); virtual; abstract;
    //Gets the list of all long functions.
    procedure GetAllLongFunctions(List: TIdentifierList);
    //Writes the list of all long functions.
    function WriteLongFunctionList(var DestFile: TextFile): Boolean;







    //Has to be overridden to generate the help on one data set.
    function GenerateGUIHelpOnData(Data: TOldGUIHelpData): String; virtual;
    //Generates the help on all datas.
    function GenerateGUIHelpDatas: String;







    property DocumentationSectionsFilter: TDocumentationSectionsFilters
                                             read FDocumentationSectionsFilter;

  public
    //Creates the generator object.
    constructor Create; override;
    //Frees 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;
    //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;





    //Returns the text in the format; text may already include other formats.
    function FormatText(TextFormat: TDocumentationTextFormat;
                        const Text: String;
                        var SkipWhitespaces: Boolean): String; override;
    //Forces a new line or paragraph to start, i.e. breaks the current line or
    //paragraph.
    function LineParagraphBreak(InsertParagraph: Boolean;
                                var SkipWhitespaces: Boolean): String;
                                                                      override;



    property FormatCommentDocMessagesID: TMessageID
                                              read FFormatCommentDocMessagesID;
  end;














implementation

uses Windows, SysUtils,
     UExtIdents,
     UDocumentationTexts;




    //list for the option "IdentifierSectionsFilter" of the generator
    //~[link TFormatCommentDoc]
var OptionItemsIdentifierSectionsFilter: TStringList = nil;
    //list for the option "FileSectionsFilter" of the generator
    //~[link TFormatCommentDoc]
    OptionItemsFileSectionsFilter: TStringList = nil;
    //list for the option "DocumentationSectionsFilter" of the generator
    //~[link TFormatCommentDoc]
    OptionItemsDocumentationSectionsFilter: TStringList = nil;