ucommentdoc.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 UCommentDoc;

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

 Some helper classes are also defined, ~[linkClass TCommentEvaluator] is the
 abstract base class of objects, that evaluate comments to include them in the
 documentation. Similar ~[linkClass TGUIHelpReader] is the abstract base class
 of objects parsing and holding data needed to generate a help on a GUI.
}

interface

uses Windows, Classes,
{$IFNDEF LINUX}
     Graphics,
{$ELSE}
     QGraphics,
{$ENDIF}
     UBaseIdents, UExtIdents,
     UOptions, UGenerationMessages, UMakeDoc, UDocumentDoc,
     UComments, UOldGUIHelpData, UImages;




type
  //the class of documentation including the comments
  TCommentDoc = class;







   { * * *  ***  * * *  ***   TCommentEvaluator   ***  * * *  ***  * * *  }



  //Do not change the order!
  //How to search for identifiers to link to.
  TLinkFindType = (
                   //no special kind given, find any matching identifier or
                   //file
                   lftAuto,
                   //find only record-like identifiers
                   lftClass,
                   //find only files
                   lftFile);



{
  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.TEvaluatorDescription. Obviously in UMakeDoc there is no type
  TEvaluatorDescription, so I guess there is a problem with the Unit-Namespaces
  with "type"-types. Strangely it does work with TExtractorDescription.

  //a description of an evaluator of comments
  TEvaluatorDescription = type TExtractorDescription;
(*
//}

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

  //class of the classes to evaluate comments
  TCommentEvaluatorClass = class of TCommentEvaluator;


  {Abstract base class of all evaluators of comments/texts/etc.. They use the
   generator to format texts in the format of the generator, but may also add
   additional parsing of the text, for instance check for special formatting
   to format some text different or inline commands to execute and insert any
   other text or other documentation items. }
  TCommentEvaluator = class
  private
    //the generator for which the comments should be evaluated
    FGenerator: TCommentDoc;

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

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



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

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





    //Returns the number of available options in evaluators 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 evaluator of comments.
    function GetOptions: TOptionWrapper;



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


    {Saves the current state of the evaluator and resets it. }
    procedure PushAndResetEnvironment; virtual; abstract;
    {Restores a previously saved state of the evaluator. }
    procedure PopEnvironment; virtual; abstract;




    {Parses the comment to a text in the format of the documentation.
    ~param Text  the text to parse
    ~param Force whether the parsing of the text should be forced
    ~result the parsed and formatted text }
    function ParseText(Text: String; Force: Boolean): String; virtual;
                                                              abstract;
    {Returns the next argument of an inline command or a section.
    ~param Text the text to read and delete the argument from
    ~result the next argument in the text }
    function GetInlineCommandArg(var Text: String): String; virtual; abstract;
    //Gets the first name of a parameter in the text and removes it.
    function ExtractParamName(var Text: String; var Param: String): Boolean;
                                                                       virtual;


    property Generator: TCommentDoc read FGenerator;
  end;










   { * * *  ***  * * *  ***   TGUIHelpReader   ***  * * *  ***  * * *  }


  //a description of a reader of data about a GUI
  TGUIHelpReaderDescription = record
    //name of the reader, may be the same as ~[link Identification]
    Name: String;
    //identification of the reader, should not contain spaces
    Identification: String;
    //a decription of the reader of data about a GUI
    Description: String;
  end;


  //class of the classes to read data about a GUI
  TGUIHelpReaderClass = class of TGUIHelpReader;

  {Abstract base class of all readers of the data about a GUI to generate a
   help about. }
  TGUIHelpReader = class
  private
    //the generator that will generate the help about the GUI
    FGenerator: TCommentDoc;

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



    //list of files to parse and generate help on a GUI from.
    FGUIHelpFiles: TStringList;



    //Returns the current file of the GUI the help is generated about.
    function GetCurrentGUIHelpFile: TOldGUIHelpData;

  protected
    //list of ~[linkClass TOldGUIHelpData]s of parsed files
    FGUIHelpData: TList;

    //index of the current file to generate documentation about a GUI;
    FCurrentGUIHelpFileIndex: Integer;         //-1 for none
    //current topic in the current file to generate documentation about a GUI
    FCurrentGUIHelpTopic: String;

  public
    //Creates reader of the data of the GUI to generate documentation about.
    constructor Create(Generator: TCommentDoc); virtual;
    //Frees the object and the read date of the GUI.
    destructor Destroy; override;



    {Returns a description of the reader of data about a GUI.
    ~result a description of the reader of data about a GUI }
    class function GetDescription: TGUIHelpReaderDescription; virtual;
                                                              abstract;


    //Returns the number of available options in readers 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 readers.
    function GetOptions: TOptionWrapper;


    {Parses all log files to generate a help for a GUI.
    ~param GUIHelpFileList the list of log files with the data of the GUI }
    procedure ParseAllLogFiles(GUIHelpFileList: TStrings); virtual; abstract;


    {Generate the linked image of the current file of documentation on a GUI.
    ~param Data the data to generate the image of
    ~result format to include the image }
    function GenerateGUIHelpImage(Data: TOldGUIHelpData): String; virtual;
                                                                      abstract;
    {Checks if all documentation topic in the help for a GUI are used. }
    procedure CheckGUIDocumentationTopicUsage; virtual; abstract;



    //Resets the reader of the data of the GUI.
    procedure ResetForNewGeneration; virtual;


    property Generator: TCommentDoc read FGenerator;
    property GUIHelpFiles: TStringList read FGUIHelpFiles;
    property GUIHelpData: TList read FGUIHelpData;
    property CurrentGUIHelpFileIndex: Integer read FCurrentGUIHelpFileIndex
                                              write FCurrentGUIHelpFileIndex;
    property CurrentGUIHelpFile: TOldGUIHelpData read GetCurrentGUIHelpFile;
    property CurrentGUIHelpTopic: String read FCurrentGUIHelpTopic
                                         write FCurrentGUIHelpTopic;
  end;











   { * * *  ***  * * *  ***   TCommentDoc   ***  * * *  ***  * * *  }




  //Defines how to format some text within the documentation.
  TDocumentationTextFormat = (
                              //emphasize the text; this makes it in most
                              //cases italic
                              dtfEmphasize,
                              //highlight the text, make it strong; this
                              //should format it bold
                              dtfStrong,
                              //formats the text as code (mono-spaced font)
                              dtfCode,
                              //formats the text preformatted, i.e. as code,
                              //and preserves the indentation and multiple
                              //spaces
                              dtfPreFormatted,
                              //formats the code as a small sample of code;
                              //should be a combination of
                              //~[link dtfPreFormatted] and ~[link dtfCode];
                              //may include a small header
                              dtfSample);




  //a section to be ignored
  TIgnoreCommentSection = (
                           //the main comment at the beginning in no special
                           //section
                           icsComment,
                           //the comment of a (or multiple) parameter(s)
                           icsParameter,
                           //the comment of the result of a function
                           icsResult,
                           //the comment on an exception, that can be thrown by
                           //a function, procedure, etc.
                           icsException,
                           //a link to an identifier, to see also for
                           //information
                           icsSee,
                           //some text pointing to additional information
                           //outside of the generated documentation
                           icsSeeText,
                           //marking the identifier as deprecated, with a
                           //comment why
                           icsDeprecated,
                           //marking the identifier as not finished, with a
                           //description what's missing
                           icsToDo,
                           //marking the identifier as missing some features,
                           //that still have to be implemented, with a
                           //description of them
                           icsFeature,
                           //gives an example of the usage of the identifier
                           icsExample,
                           //names the author of the identifier/file,
                           //optionally with some text describing his changes
                           //etc.
                           icsAuthor,
                           //gives a version this identifier/file was
                           //introduced or something changed
                           icsVersion);

  //the sections to be ignored
  //~see IgnoredCommentSections
  TIgnoreCommentSections = set of TIgnoreCommentSection;