umakedoc.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 UMakeDoc;

{Contains the abstract base-class of all generators of documentation:
 ~[linkClass TMakeDoc]. There is a whole hierarchy of classes with this base
 class adding additional functionality and eventually implementing several
 different document formats. All real generators of documentation derive not
 directly from TMakeDoc but subclass
 ~[linkClass UFormatCommentDoc.TFormatCommentDoc] instead, that implements the
 assembling of lists and comments. It in turn subclasses
 ~[linkClass UCommentDoc.TCommentDoc] that implements the finding and general
 parsing of comments. It again subclasses
 ~[linkClass UDocumentDoc.TDocumentDoc], that implements general methods needed
 for generating documentation. TMakeDoc implements the general interface,
 messages, options of generators and some general methods about parsed
 data.

 The helper class ~[linkClass TCommentExtractor] is also defined in this unit,
 it is the abstract base class of objects that return comments for the
 documentation of identifiers and files.

 The ~[link GeneratorClasses list of all available non-abstract generators] is
 administrated here.
}


interface

uses Classes, IniFiles, Graphics, 
     UProgress,
     UPascalConsts,
     UBaseIdents, UExtIdents,
     UOptions, UGenerationMessages,

     UGUIHelpIndexContent,
     UComments;




type

  {The messages that can be generated by the generators in the class
   ~[link TMakeDoc]. }
  TMakeDocMessageKind = (
                         //the feature requested is not supported (for the
                         //specific generator)
                         mdmkNotSupported,
                         //the class (object- or class-modell) has fields
                         //declared without a scope given before them (just
                         //for information)
                         mdmkUnscopedFields,
                         //in invalid name of an identifier has been found
                         mdmkInvalidIdentifier,
                         //an unsupported or invalid graphic file should have
                         //been included in the documentation
                         mdmkImageFormatNotSupported
                        );




  //a description of a generator of documentation
  TGeneratorDescription = record
    //name of the generator, may be the same as ~[link Identification]
    Name: String;
    //identification of the generator, should not contain spaces
    Identification: String;
    //a decription of the generator
    Description: String;
  end;




  //The abstract base-class of all generators of documentation.                       
  TMakeDoc = class;

  //class of the classes to generate documentation
  TMakeDocClass = class of TMakeDoc;


  








  



















   { * * *  ***  * * *  ***   TCommentExtractor   ***  * * *  ***  * * *  }


{
  Error in Delphi (4):
  If " = type " is used, I got in another unit the "Fatal Error" that it has
  been compiled with "a different" version of
  UMakeDoc.TExtractorDescription. Obviously in UMakeDoc there is no type
  TExtractorDescription, so I guess there is a problem with the Unit-Namespaces
  with "type"-types.

  Well, ok, that's wrong, it only does so with TEvaluatorDescription further
  down.
}

  //a description of an extractor of comments
  TExtractorDescription = type TGeneratorDescription;

//}
{
  //a description of an extractor of comments
  TExtractorDescription = record
    //name of the extractor of comments, may be the same as
    //~[link Identification]
    Name: String;
    //identification of the extractor of comments, should not contain spaces
    Identification: String;
    //a decription of the extractor of comments
    Description: String;
  end;
}


  //class of the classes to extract comments
  TCommentExtractorClass = class of TCommentExtractor;


  {Abstract base class to give comments to a generator of documentation. These
   can be extracted from the source code, but it's also possible to store them
   in external files, f.i. ini-files, or in a database or anywhere else. Only a
   descendant of this class has to be created implementing the extraction from
   the source. It's also possible to create an extractor, that will use the
   comments inside the source code, but handle their format different, for
   example to use the existing comments without any formats or a different
   format or to find them at an alternative position withing the source code. }
  TCommentExtractor = class
  private
    //the generator for which the comments should be extracted
    FGenerator: TMakeDoc;

    //an object to access the options of the extractor through a more general
    //interface
    FOptionAccessor: TOptionWrapper;

  protected

    property Generator: TMakeDoc read FGenerator;
  public

    //Creates the object and saves the reference on the generator.
    constructor Create(Generator: TMakeDoc); virtual;
    //Frees the object.
    destructor Destroy; override;



    {Returns a description of the extractor of comments.
    ~result a description of the extractor of comments }
    class function GetDescription: TExtractorDescription; virtual; abstract;

    //Checks if the extractor can work with the generator.
    class function Supports(GeneratorClass: TMakeDocClass): Boolean; virtual;





    //Returns the number of available options in extractors of this class.
    class function GetOptionCount: Cardinal; virtual;
    //Gets a description of an option.
    class procedure GetOptionDescription(Index: Cardinal;
                                         var Desc: TOptionDescription);
                                                                       virtual;
    //Gets the value of an option.
    function GetOption(Index: Cardinal): TOptionValue; virtual;
    //Sets the value of an option.
    procedure SetOption(Index: Cardinal; const Value: TOptionValue); virtual;


    //Returns an object to edit the options of the extractor of comments.
    function GetOptions: TOptionWrapper;


    //Resets the attributes to ready the extractor for a new generation.
    procedure ResetForNewGeneration; virtual;



    {Returns the comments about the identifier.
    ~param Ident the identifier whose comments should be returned
    ~result the comments about the identifier }
    function Comment(Ident: TIdentifier): TComment; virtual; abstract;
    {Returns the comments about the file.
    ~param AFile the file whose comments should be returned
    ~result the comments about the file }
    function CommentOfFile(AFile: TPascalFile): TComment; virtual; abstract;

    //Returns the additional user documentation in a file.
    function UserDocumentation(Text: String): TComment; virtual;
    //Returns the comments in a file with documentation as help of a GUI.
    function GUIHelpDocumentation(Text: String): TComment; virtual;


    //Sets the names of sections not to be recognized as sections on its own.
    function SetIgnoredSectionNames(IgnoredNames: TStrings): Boolean; virtual;

    {Returns the text as a comment. This method has to be implemented even if
     the extractor does not need to split one big text into sections because
     it is also called from the generator to split user documentation and help
     about a GUI into its parts.
    ~param Text  the text of a comment to split in sections
    ~param Force whether the sectioning of the text should always be done, even
                 if it is disabled
    ~result the text as comments }
    function Sectionize(Text: String; Force: Boolean): TComment; virtual;
                                                                 abstract;
  end;
























   { * * *  ***  * * *  ***   TMakeDoc   ***  * * *  ***  * * *  }





  //the capabilities of the generators of documentation
  TGeneratorCapability = (
                          //generator can use extracted comments (needs an
                          //extractor)
                          gcExtractsComments,
                          //generator can generate help on a GUI
                          gcGUIHelp);

  //the capabilities of the generators of documentation
  TGeneratorCapabilities = set of TGeneratorCapability;



  //scopes of identifiers within files
  TSpecialFileScope = (
                       //in the implementation part of a unit
                       fsImplementation,
                       //in the interface of a unit
                       fsInterface,
                       //in a program or library
                       fsProgram);

  //scopes of identifiers within files
  TSpecialFileScopes = set of TSpecialFileScope;



  //kinds of identifiers of a file that can be filtered by
  TFilterIdentifierKinds = (
                            fikVariable,       //variables
                            fikThreadVariable, //thread-variables
                            fikConstant,       //constants
                            fikResourceString, //resource strings
                            fikFunction,       //functions and procedures
                            fikSimpleType);    //all types besides classes




  //the kind of documentation generated by the generator
  TDocGenerationKind = (
                        //generate documentation about delphi source code
                        dgkDelphiDoc,
                        //generate only user documentation
                        dgkUserDoc,
                        //generate help on a GUI of a program
                        dgkGUIHelp);



  {Called when the position of a newly generated message has to be set.
  ~param Message the new message
  ~param Sender  the generator logging the message }
  TGeneratorMessageSetPositionCallBack = procedure(Message: TGeneratorMessage;
                                                   Sender: TMakeDoc) of object;


  {Called when a message is generated by a generator.
  ~param Message   the generated message
  ~param Sender    the generator generating the message while generating
  ~param AddToList whether the message should be added to the list, default is
                   True }
  TGeneratorMessageEvent = procedure(Message: TGeneratorMessage;
                                     Sender: TMakeDoc;
                                     var AddtoList: Boolean) of object;



  //the information to generate documentation about/with
  TGenerationInformation = record
    //what kind of documentation should be generated
    Kind: TDocGenerationKind;
    //the parsed source code to generate documentation about
    PascalSource: TFileList;
    //the list of files with additional user documentation
    UserDocumentation: TStrings;
    //the list of log files about a GUI to generate documentation about
    GUIHelpLogFiles: TStrings;
    //an alternative content for the main index when generating help on a GUI
    //(maybe later also for user documentation or even additional for
    //documentation of source code);~[br]
    //this root itself is not included, only its sub-topics; if it is nil or
    //contains no sub-topics the default content will be used for the main
    //index of the documentation
    MainIndexRoot: TGUIMainIndexEntry;
  end;



  {The abstract base-class of all generators of documentation. It has a whole
   hierarchy of classes adding additional functionality and eventually
   implementing several different document formats. All real generators of
   documentation derive not directly from TMakeDoc but subclass
   ~[linkClass UFormatCommentDoc.TFormatCommentDoc] instead, that implements
   the assembling of lists and comments. It in turn subclasses
   ~[linkClass UCommentDoc.TCommentDoc] that implements the finding and general
   parsing of comments. That one subclasses