uformatcommentdoc.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 UFormatCommentDoc;

{Contains the abstract base-class of all generators of documentation that
 generates several specific lists and information: ~[linkClass
 TFormatCommentDoc]. It serves mainly handy methods to be called by the
 descendant generator classes. All generators of documentation subclass it.
 At the moment there are four final generators available:
 ~[linkClass UHTMLDoc.THTMLDoc], ~[linkClass UWinHelpDoc.TWinHelpDoc],
 ~[linkClass ULaTeXDoc.TLaTeXDoc] and ~[linkClass UPDFDoc.TPDFDoc].
 Another test:
~author Gerold Veith creating the file
~author Gerold Veith changing it
~version 1.0 created
~version 1.1 changed
~see TFormatCommentDoc }

interface

uses Classes,
     UPascalConsts,
     UBaseIdents,
     UOptions, UGenerationMessages, UMakeDoc,
     UCommentExtraction, UOldGUIHelpData, UComments, UCommentDoc;



   { * * *  ***  * * *  ***   TFormatCommentDoc   ***  * * *  ***  * * *  }




type
  {The needed values to format text in a special way used by
   ~[link TFormatCommentDoc.FormatText]. }
  TFormatSetting = record
     //the text to insert before the text to format
     Pre: String;
     //the text to insert before the text to format
     Post: String;
     //if following whitespaces should be omitted
     SkipWhitespaces: Boolean;
   end;

  {The needed values to format texts in special ways. The field
   ~[link TFormatCommentDoc.FFormatSettings] of this type is used
   by ~[link TFormatCommentDoc.FormatText]. }
  TFormatSettings = array[TDocumentationTextFormat] of TFormatSetting;


  {The needed values to insert line or paragraph breaks. The field
   ~[link TFormatCommentDoc.FLineParagraphBreak] of this type is used
   by ~[link TFormatCommentDoc.LineParagraphBreak]. }
  TLineBreakParagraph = array[Boolean] of record
                                 //the text to insert before the text to format
                                 Format: String;
                                 //if following whitespaces should be omitted
                                 SkipWhitespaces: Boolean;
                               end;



  {A lot of (format(ted)) strings used in the several methods of ~[link
   TFormatCommentDoc] to create documentation.}
  TFormatStrings = record
    //format before additional attributes, author and version
    FAdditionalAttributePre: String;
    //format after additional attributes, author and version
    FAdditionalAttributePost: String;
    //format before list of authors
    FAuthorsPre: String;
    //format after list of authors
    FAuthorsPost: String;
    //format before list of versions
    FVersionsPre: String;
    //format after list of versions
    FVersionsPost: String;
    //format before list and header of additional attributes
    FAdditionalAttributesPre: String;
    //format before list of additional attributes and after the header text
    FAdditionalAttributesMiddle: String;
    //format after list of additional attributes
    FAdditionalAttributesPost: String;

    //format of see-also links in identifier comments;
    FSeePreIdent: String;           //before the link to the identifier/file
    //format of see-also links in identifier comments;
    FSeePostIdent: String;          //after the link to the identifier/file
    //format of see-also links in file comments;
    FSeePreFile: String;            //before the link to the identifier/file
    //format of see-also links in file comments;
    FSeePostFile: String;           //after the link to the identifier/file

    //beginning of an example of/to an identifier before the number of the
    FExamplePreIdent: String;       //example
    //beginning of an example of/to an identifier after the number of the
    FExampleMiddleIdent: String;    //example and before the example itself
    //end of an example of/to an identifier
    FExamplePostIdent: String;
    //beginning of an example of/to an file before the number of the example
    FExamplePreFile: String;
    //beginning of an example of/to an file after the number of the example and
    FExampleMiddleFile: String;     //before the example itself
    //end of an example of/to an file
    FExamplePostFile: String;
    FExampleHeader: String;         //text before list of all examples
    FExampleFooter: String;         //text after list of all examples

    //format of "deprecated", "ToDo" and "feature" sections, before their title
    FSpecialPre: String;
    //format of "deprecated", "ToDo" and "feature" sections, between the title
    FSpecialMiddle: String;         //and the content
    //format at the end of "deprecated", "ToDo" and "feature" sections
    FSpecialPost: String;
    //format at the beginning of a list of "deprecated", "ToDo" or "feature"
    FSpecialListPre: String;        //sections
    //format at the end of a list of "deprecated", "ToDo" or "feature" sections
    FSpecialListPost: String;
    //format at the beginning of all lists of "deprecated", "ToDo" or "feature"
    FSpecialsPre: String;           //sections
    //format at the end of all lists of "deprecated", "ToDo" or "feature"
    FSpecialsPost: String;          //sections

    //format before the main comment of identifiers
    FCommentPreFile: String;
    //format after the main comment of identifiers
    FCommentPostFile: String;
    //format before the main comment of files
    FCommentPreIdent: String;
    //format after the main comment of files
    FCommentPostIdent: String;

    //format before all extended documentation, besides the main comment and
    //the special "deprecated", "ToDo" and "feature" sections
    FExtendedInfoPre: String;
    //format after all extended documentation, besides the main comment and the
    //special "deprecated", "ToDo" and "feature" sections
    FExtendedInfoPost: String;

    //format and text before a list of parameters
    FParamHeader: String;
    //format before the name of a parameter
    FParamPre: String;
    //format between the name of a parameter and its comment
    FParamMiddle: String;
    //format after the comment of a parameter
    FParamPost: String;
    //format after a list of parameters
    FParamFooter: String;

    //format and text before the comment of the result of a function
    FResultPre: String;
    //format after the comment of the result of a function
    FResultPost: String;

    //format and text before a list of possible exceptions of a function
    FExceptionHeader: String;
    //format before the name of a possible excception in a function
    FExceptionPre: String;
    //format between the name of a possible excception and its comment
    FExceptionMiddle: String;
    //format after the comment of a possible excception in a function
    FExceptionPost: String;
    //format after a list of possible exceptions of a function
    FExceptionFooter: String;

    //format and text before a link to an overriden method
    FOverridesPre: String;
    //format after a link to an overriden method
    FOverridesPost: String;

    //format and text before a list of links of overridding methods
    FOverriddenByPre: String;
    //format after a list of links of overridding methods
    FOverriddenByPost: String;

    //format and text before a list of global identifiers in a function
    FGlobalsHeader: String;
    //format of the end of a list of global identifiers in a function
    FGlobalsEnd: String;
    //format and text before a list of called global functions in a function
    FCallsHeader: String;
    //format of the end of a list of called global functions in a function
    FCallsEnd: String;
    //format and text before a list of functions the identifier is used by
    FUsedHeader: String;
    //format and text before a list of functions the function is used by
    FUsedHeaderFunc: String;
    //format of the end of a list of functions the identifier/function is used
    FUsedEnd: String;              //by


    //format before the lists of files using a file
    FUsingFiles: String;
    //format after the lists of files using a file
    FUsingFilesEnd: String;
    //format before the list of program-/library-/package-files using a file
    FUsingPrograms: String;
    //format after the list of program-/library-/package-files using a file
    FUsingProgramsEnd: String;
    //format before the list of units using a file in their interface
    FUsingInterface: String;
    //format after the list of units using a file in their interface
    FUsingInterfaceEnd: String;
    //format before the list of units using a file in their implementation part
    FUsingImplementation: String;
    //format after the list of units using a file in their implementation part
    FUsingImplementationEnd: String;

    //format before the list of packages requiring another package
    FRequiredBy: String;
    //format after the list of packages requiring another package
    FRequiredByEnd: String;





    //format and text before the list of (deprecated) parameters of a
    FFileCommentParameterPre: String;               //project/program
    //format after the list of (deprecated) parameters of a project/program
    FFileCommentParameterPost: String;

    //format and text before the list of required packages of a package
    FFileCommentRequiredPackagesPre: String;
    //format after the list of required packages of a package
    FFileCommentRequiredPackagesPost: String;
    //format and text if a package requires no other package
    FFileCommentRequiredPackagesNone: String;
    //format and text before the list of required packages of a project
    FFileCommentRequiredPackagesProjectPre: String;      //(program, library)
    //format after the list of required packages of a project
    FFileCommentRequiredPackagesProjectPost: String;

    //format and text before the list of exported identifiers
    FFileCommentExportsPre: String;
    //format after the list of exported identifiers
    FFileCommentExportsPost: String;
    //format and text if a library exports no identifiers
    FFileCommentExportsNone: String;

    //format and text of the header for the list of used units of a file
    FFileCommentUsingHeader: String;
    //format and text before the list of used units in the interface of a unit
    FFileCommentUsingInterfacePre: String;
    //format after the list of used units in the interface of a unit
    FFileCommentUsingInterfacePost: String;
    //format and text of the header for the list of used units in a project
    FFileCommentUsingProject: String;
    //format and text of the header for the list of contained units
    FFileCommentUsingPackage: String;           //in a package
    //format and text of the header for the list of used units in the
    FFileCommentUsingImplementation: String;    //implementation part of a unit
    //format and text if the unit uses no units in its implementation part
    FFileCommentUsingNoneImplementation: String;
    //format and text before the list of used units in the interface of a unit
    FFileCommentUsingPre: String;
    //format after the list of used units in the interface of a unit
    FFileCommentUsingPost: String;
    //format and text if the project uses no units/package contains no units
    FFileCommentUsingNone: String;

    //format and text of the header for the comment of the file
    FFileCommentCommentHeader: String;






    //the format used to create an "icon" for abstract methods
    FAbstractIconText: String;
    //the format used to create an "icon" for read-only properties
    FReadOnlyIconText: String;
  end;






  //type to filter some sections of the documentation of an identifier
  TIdentifierSectionsFilter = (
                               //don't list the identifiers using this one
                               isfUsedBy,
                               //don't list the functions calling this one
                               isfCalledBy,
                               //don't list the identifiers used by this
                               isfGlobals,                 //function
                               //don't list the functions used by this function
                               isfCalls,
                               //don't show the function that is overridden
                               isfOverrides,               //one
                               //don't show the functions that override this
                               isfOverriddenBy);           //one


  //type to filter some sections of the documentation of a file