uicdocumentdoc.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 UICDocumentDoc;

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

{$include empty.inc}

interface

uses Windows, Classes, Graphics,
     UPascalConsts,
     UBaseIdents,
     UVectorGraphics,
     UDocumentationTexts,
     UOptions, UGenerationMessages, UMakeDoc,
     UICNodes;




      //the name of an ini file mapping the help contexts to their destinations
const HelpContextIniFileName = 'HelpContexts.ini';
      //the name of a simple file containing the mapping from help contexts to
      //the destinations
      HelpContextMappingFileName = 'HelpContexts.txt';

      //the name of the ini section containing the mapping from help contexts
      HelpContextIniSection = 'HelpContexts';


      //an URL to inform the user about SVG and about available viewers
      SVGGetViewerURL1 = 'http://wiki.svg.org/Viewer_Implementations#Browser_Plug-Ins';
      //another URL to inform the user about SVG and about available viewers
      SVGGetViewerURL2 = 'http://www.svgi.org/';




type

   { * * *  ***  * * *  ***   TICDocumentDoc   ***  * * *  ***  * * *  }


  {The messages that can be generated by the generators in the class
   ~[link TICDocumentDoc]. }
  TICDocumentDocMessageKind = (
    //the implemented interface redirected to a property wasn't found in the
    //list of implemented interfaces by the class
    ddmkImplementedInterfaceOfPropertyDoesNotMatch,
    //the method of an interface redirected to another method of an interface
    //was not found in the list of implemented interfaces by the class
    ddmkInterfaceOfMethodNotImplemented,
    //help context don't match, i.e. it has already been used for another topic
    //or the topic already has another help context
    ddmkHelpContextMismatch
  );



  //an index in the list of all identifiers and files for a character;
  //will be used as an array, sorted by the character, only entries which occur
  //in the list will be in the final array
  TIndexCharIndex = record
                      //the character the identifiers or files start with,
                      //either a capital letter ('A'..'Z'),
                      //the underscore ('_') or a star ('*') for all other
                      //non-ASCII characters (>#127)
                      StartsWith: Char;
                      //the index of the first entry not starting anymore with
                      //the character
                      EndPlusOne: Integer;
                    end;



  //the possible file formats to generate the class tree and usage of files in
  TFileClassTreeFileFormat = (
                              //generate as XFig file
                              fctffXfig,
                              //generate as Enhanced Windows Meta File
                              fctffEWMF,
                              //generate as Scalable Vector Graphics
                              fctffSVG);

  //the possible file formats to generate the class tree and usage of files in
  TFileClassTreeFileFormats = set of TFileClassTreeFileFormat;



  {The abstract base-class of all generators of documentation (with the new
   internal system). To parse the comments in the source code the also abstract
   sub-class ~[linkClass UICCommentDoc.TICCommentDoc] is available, so this
   class is only directly subclassed by that class.

   It defines the general interface to generate the documentation as it will be
   implemented in the concrete generators.

   It also manages the help contexts and introduces a few virtual methods for
   the ~[link UCommentScanner.TCommentScanner scanner of comments] that will
   hold a reference on a generator of this class.

   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. }
  TICDocumentDoc = class(TMakeDoc)
  private
    //ID of the messages of this class
    FICDocumentDocMessagesID: TMessageID;


    //whether the files showing the inter-dependence between the files should
    //be generated
    FGenerateFileTreeFiles: Boolean;
    //whether the files showing the inheritance tree of classes should be
    //generated
    FGenerateClassesTreeFiles: Boolean;
    //the formats to generate the files showing the inter-dependence between
    //files and the inheritance tree of classes in
    FGenerateFileClassTreeFormats: TFileClassTreeFileFormats;

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

    //whether an ini file mapping the help contexts to their destinations
    //should be generated
    FGenerateHelpContextIniFile: Boolean;
    //whether a simple file containing the mapping from help contexts to the
    //destinations should be created
    FGenerateHelpContextMappingFile: Boolean;


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


  protected

    //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;

    //call back procedure to get links on files in SVG diagrams of their usage;
    //nil by default
    FFileUsageDiagramCallBack: TGetFileURLCallBack;
    //call back procedure to get links on class in SVG diagrams of the
    //hierarchy; nil by default
    FClassTreeDiagramCallBack: TGetClassURLCallBack;



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



    //Adds the name of the identifier to the node.
    procedure AddIdentifierText(const IdentifierName: String;
                                AddTo: TICNCompound);
    //Adds the reserved word to the node.
    procedure AddReservedWord(const ReservedWord: String;
                              AddTo: TICNCompound);
    //Adds the string to the node.
    procedure AddString(const StringText: String;
                        AddTo: TICNCompound);










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

    //Adds the list of files.
    procedure AddFileList(AddTo: TICNCompound);
    {Writes the list of files, the text is generated by ~[link AddFileList].
    ~param Node the node containing the list of files }
    procedure WriteFileList(Node: TICNode); 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);

    //Adds the hierarchy of the kind of the record-like types to the node.
    procedure AddClassList(Kind: TRecordKind; AddTo: TICNCompound);
    {Writes the hierarchy of the kind of the record-like types.
    ~param Kind the kind of the record-like types (record/class/interface/...)
    ~param Node the node containing the tree of classes (added by
                ~[link AddClassList]) }
    procedure WriteClassTree(Kind: TRecordKind; Node: TICNode); 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);









    {Writes the splitted up list of identifiers and files into the
     documentation.
    ~param TopicName       the internal name of the topic to write the list in
    ~param DescriptionText the entry for the localization of the description of
                           the list
    ~param KeyWordListText the entry for the localization of the keywords for
                           the list
    ~param Idents          the list of the identifiers directly defined in
                           files to be written
    ~param Classes         the list of the record-like types to be written
    ~param Files           the list of the files to be written
    ~result whether the lists have been written }
    function WriteListOfIdentifiersAndFiles(const TopicName: String;
                                          DescriptionText,
                                          KeyWordListText: TDocumentationTexts;
                                          Idents, Classes: TIdentifierList;
                                          Files: TIdentifierFileList): Boolean;
                                                             virtual; abstract;

    //Writes a list of identifiers and files.
    function WriteIdentifiersAndFilesList(const TopicName: String;
                                          DescriptionText,
                                          KeyWordListText: TDocumentationTexts;
                                          List: TIdentifierFileList): Boolean;



    {Generates an index about all identifiers and files.
     Should call ~[link Progress.SetProgressText] before and
     ~[link Progress.StepProgress] after each processed character.
    ~param List        the sorted list of all identifiers and files to generate
                       the index of
    ~param CharIndices the indices defining the ranges of identifiers starting
                       with the same letter }
    procedure DoGenerateIndex(List: TIdentifierFileList;
                              const CharIndices: array of TIndexCharIndex);
                                                             virtual; abstract;

    //Generates an index about all identifiers and files.
    function GenerateIndex: Char;






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





    //Called after the documentation has been successfully generated.
    procedure PostProcessDocumentation; virtual;

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




    property HelpContextList: TStringList read FHelpContextList;

    property GenerateFileTreeFiles: Boolean read FGenerateFileTreeFiles;
    property GenerateClassesTreeFiles: Boolean read FGenerateClassesTreeFiles;
    property GenerateFileClassTreeFormats: TFileClassTreeFileFormats
                                            read FGenerateFileClassTreeFormats;
    property MinLongFunctionLines: Integer read FMinLongFunctionLines;
  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.