udocumentdoc.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 UDocumentDoc;

{Contains the abstract base-class of all generators of documentation:
 ~[linkClass TDocumentDoc]. All generators of documentation will subclass it.
 To parse the comments in the source code the also abstract sub-class
 ~[linkClass UCommentDoc.TCommentDoc] is available, so this class is only
 directly subclassed by that class.
}

{$include empty.inc}

interface

uses Classes,
     UPascalConsts,
     UBaseIdents, UExtIdents,
     UDocumentationTexts,
     UOptions, UGenerationMessages, UMakeDoc;


type

  {Only used as a marker for the generators of the old system and to move them
   in the tree view below the new ones.
  ~deprecated will be removed as soon as all generators have been transfered to
              the new internal system of representing comments - the
              ~[linkUnit UICNodes COM] - Comment Object Model }
  TOldDeprecatedGeneratorsDoc = class(TMakeDoc)
  end;


   { * * *  ***  * * *  ***   TDocumentDoc   ***  * * *  ***  * * *  }


  {A lot of (format(ted)) strings used in the several methods of ~[link
   TDocumentDoc] to create documentation.}
  TFormatStrings = record
    //the text starting links
    FPreLinkText: String;
    //the text between the destination of a link and its text
    FMiddleLinkText: String;
    //the text ending links
    FPostLinkText: String;


    //the separator between classes in the inheritance list of classes
    FAncestorListArrow: String;
    //the format string before an abstract identifier in the inheritance list
    FAncestorListAbstractPre: String;
    //the format string after an abstract identifier in the inheritance list
    FAncestorListAbstractPost: String;
    //the string to insert, if a class in unknown; should end with the same
    //text as ~[link FAncestorListArrow]
    FAncestorListMissing: String;
    //the format string before the final identifier
    FAncestorListFinalPre: String;
    //the format string after the final identifier (and at the end)
    FAncestorListFinalPost: String;



    //format of project files (before the link to the file)
    FProjectFormatPre: String;
    //format of project files (after the link to the file)
    FProjectFormatPost: String;

    //format of units (before the link to the file)
    FUnitFormatPre: String;
    //format of units (after the link to the file)
    FUnitFormatPost: String;
    //format after the list of units of a project/independent units
    FUnitListFormatPost: String;

    //the heading and format of the independent units
    FIndependentFiles: String;

    //text after list of files (before included files)
    FFileListAfterList: String;

    //the heading and format of the included files
    FIncludedFiles: String;
    //format of included files (before it)
    FIncludedFilePre: String;
    //format of included files (after it)
    FIncludedFilePost: String;
    //format after the list of included files
    FIncludedFileListEnd: String;




    //format of abstract identifiers (before the identifier)
    FAbstractFormatPre: String;
    //format of abstract identifiers (after the identifier)
    FAbstractFormatPost: String;

    //"implements" text for classes, that implement interfaces
    FClassListImplements: String;
    //text after an class entry in the list (including implemented interfaces)
    FClassListAfterClassEntry: String;
    //text before derived classes (sub-tree)
    FClassListSubClassesPre: String;
    //text after derived classes (sub-tree)
    FClassListSubClassesPost: String;
    //text after a class and all derived classed (sub-tree)
    FClassListAfterClass: String;
    //text before unknown parent classes
    FClassListUnknownParentPre: String;
    //text after unknown parent classes, before the derived classes
    FClassListUnknownParentMiddle: String;
    //text after derived classes of unknown parent classes
    FClassListUnknownParentPost: String;
    //no classes (no types of that record-like type)
    FClassListNoClasses: String;
    //text after the tree of the classes (before links)
    FClassListAfterClassTree: String;
  end;




  {The messages that can be generated by the generators in the class
   ~[link TDocumentDoc]. }
  TDocumentDocMessageKind = (
                             //the implemented interface redirected to a
                             //property wasn't found in the list of implemented
                             //interfaces by the class
                             ddmkImplementedInterfaceOfPropertyDoesNotMatch,
                             //the method implementing a method of an
                             //implemented interface was redirected to another
                             //method, but the interface was not found in the
                             //list of implemented interfaces by the class
                             ddmkInterfaceOfMethodNotImplemented
                            );








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

   Several functions for creating links on identifiers and list of identifiers
   are introduced in this class that may be called by subclasses.

   The method ~[link .WriteFileTreeFiles] can be used to generate files
   of all files and their and dependance among each other, while ~[link
   .WriteClassesTreeFiles] writes files of all types and their
   inheriteance-tree. If and what kind of files will be generated can be set in
   the options.

  ~deprecated this part of the hierarchy of generators will be deprecated,
              it will be created anew, those generators will use the
              ~[linkUnit UICNodes COM] - Comment Object Model }
  TDocumentDoc = class(TOldDeprecatedGeneratorsDoc)
  private
    //ID of the messages of this class
    FDocumentDocMessagesID: TMessageID;

    //if the files showing the inter-dependence between the files should be
    //generated
    FGenerateFileTreeFiles: Boolean;
    //if the files showing the inheritance tree of classes should be generated
    FGenerateClassesTreeFiles: Boolean;
    //if X-fig files should be generated
    FGenerateXFigFiles: Boolean;
    //if WMF files should be generated
    FGenerateWMFFiles: Boolean;



  protected
    //several formats and texts used to generate documentation with the methods
    FDocumentFormats: TFormatStrings;



    //base name (without extension) of files showing the files and their
    //dependance among each other
    FFileTreeFileBaseName: String;
    //base name (wihtout extension) of files showing all classes (record-like
    //types) of that kind and their inheritance from each other.
    FClassTreeFileBaseName: array[TRecordKind] of String;





    //Returns the token (formatted) in the format of the documentation.
    function FormatStringToken(const StringToken: String): String; virtual;





    //Returns a string containing a link to the given file.
    function GetFileNameLink(TheFile: TPascalFile): String; virtual;
    //Returns a string containing a link to the given identifier.
    function GetIdentNameLink(Ident: TIdentifier;
                              WriteFile: Boolean = False): String; virtual;
    //Returns a string containing a link to the given identifier inside a
    //record-like type.
    function GetRecordFieldNameLink(Ident: TIdentifier;
                                    WriteRecord: Boolean = False): String;
                                                                       virtual;







    //Returns the parameters of the program.
    function GetProgramParameters(ProgramFile: TPascalFile): String;
    //Returns the list of all required packages.
    function GetRequiredPackages(PackageFile: TPascalFile): String;
    //Returns the text of an exported function/identifier.
    function GetExportsDeclaration(Ident: TExportIdentifier): String;
    //Returns the list of all exported functions/identifiers.
    function GetExports(AFile: TPascalFile): String;
    //Returns the list of all used/contained units in a part.
    function GetUnitList(ForFile: TPascalFile; FilePart: TFilePart): String;



    //Returns the inheritance list of the record-like type.
    function GetAncestorList(Ident: TRecordType): String;
    //Returns a list of all implemented interfaces.
    function GetInterfaceLinks(Ident: TRecordType): String;
    //Returns a list of all in parent-classes implemented interfaces.
    function GetParentInterfaceLinks(Ident: TRecordType): String;
    //Returns a list of the direct descendants of the record-like type.
    function GetDirectDescendantList(Ident: TRecordType): String;
    //Returns a list of the classes implementing the interface.
    function GetImplementingClassesList(Ident: TRecordType): String;
    //Returns two lists of links to methods overriding the given one.
    procedure GetOverridingMethods(Method: TFunction; RecType: TRecordType;
                                   var Direct, Indirect: String;
                                   IndirectMethods: Boolean);
    //Returns a list of all abstract methods in the class.
    function GetStillAbstractMethods(AClass: TRecordType): String;














    //Writes files of all files and their dependance among each other.
    procedure WriteFileTreeFiles;

    {Gets the links to the generated files by ~[link WriteFileTreeFiles].
    ~result a text including (if possible) a link to the generated files in the
            format of the documentation }
    function GetFileListFileLinks: String; virtual; abstract;
    //Gets the text of the list of files.
    function GetFileListText: String;
    {Writes the list of files, the text is generated by ~[link
     GetFileListText].
    ~param Text the text of the list of files }
    procedure WriteFileList(const Text: String); virtual; abstract;

    {Writes the documentation about the file.
    ~param AFile the file whose documentation should be written }
    procedure WriteFileDocumentation(AFile: TPascalFile); virtual; abstract;


    //Writes the documentation of all files.
    procedure WriteFilesDocumentation;











    //Writes files of all classes of that kind and their inheritance from each
    //other.
    procedure WriteClassesTreeFiles(Kind: TRecordKind;
                                    TopLevelClasses: TStrings);

    {Gets the text of an indentation by the given depth.
    ~param Indent the depth of the class in the inheritance tree
    ~result an indentation by the given depth }
    function ClassListIndent(Indent: Integer): String; virtual; abstract;
    {Write the links to the generated files by ~[link WriteClassesTreeFiles].
    ~param Kind the kind of the record-like types (record/class/interface/...)
    ~result a text including (if possible) a link to the generated files in the
            format of the documentation }
    function ClassListFileLinks(Kind: TRecordKind): String; virtual; abstract;
    //Gets the text of the hierarchy of the kind of the record-like types.
    function GetClassListText(Kind: TRecordKind): String;
    {Writes the hierarchy of the kind of the record-like types.
    ~param Kind the kind of the record-like types (record/class/interface/...)
    ~param Text the text (by ~[link GetClassListText]) of the tree of classes }
    procedure WriteClassList(Kind: TRecordKind; const Text: String); virtual;
                                                                     abstract;

    {Writes the documentation of the record-like type.
    ~param Ident the record-like type whose data should be written }
    procedure WriteClassDocumentation(Ident: TRecordType); virtual; abstract;


    //Writes the documentation of all record-like types of that kind.
    procedure WriteClassesDocumentation(Kind: TRecordKind);