uilcomment.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) 2006-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 UILComment;

{Contains classes to hold comments, ~[link TICDocComment] is the abstract base
 class, ~[link TICIdentifierComment] holds the comment of an identifier or file
 which will be converted to the final documentation of that identifier or file
 and saved in an object of the class ~[link TICSimpleComment].

 The abstract base class ~[link TICComments] manages a list of comments, its
 specialized sub class ~[link TICSourceComments] does this for the comments of
 all identifiers and files. It uses the class ~[link TICIdentifierComments],
 which maps the identifiers to their comments and documentations, and in turn
 enlists the assistance of the class ~[link TIdentifierListAdapter] to map
 identifiers to their comments and documentation.

 The comments and documentations consist of the ~[em COM] as defined in unit
 ~[linkUnit UICNodes], it is based on the class hierarchy based on the
 abstract class ~[link TICNode].
}


interface

uses Classes,
     UBaseIdents, UExtIdents,
     UComments,
     UMakeDoc,
     UICNodes;

type

   { * * *  ***  * * *  ***   TICDocComment   ***  * * *  ***  * * *  }


  {The abstract base class to represent a comment or documentation as part of
   the generated documentation. }
  TICDocComment = class
  private
    //the owner of contained nodes, repsonsible for freeing the nodes
    FNodeOwner: TICNodeOwner;

    //help context of the contained comment/documentation;
    //default: 0: no special help context
    FHelpContext: THelpContext;
    //keywords associated with the comment/documentation
    //~todo implement
    //~todo sorted? or not (than they could be specified by importance)?
    FKeyWords: TStringList;
  public
    //Creates the object.
    constructor Create;
    //Frees the comments and the object.
    destructor Destroy; override;


    property NodeOwner: TICNodeOwner read FNodeOwner;

    property HelpContext: THelpContext read FHelpContext write FHelpContext;
    property KeyWords: TStringList read FKeyWords;
  end;



   { * * *  ***  * * *  ***   TICSimpleComment   ***  * * *  ***  * * *  }

  {Contains some piece of the documentation. }
  TICSimpleComment = class(TICDocComment)
  private
    //the piece of documentation
    FContent: TICNCompound;
  public
    //Creates the object.
    constructor Create;

    property Content: TICNCompound read FContent;
  end;





   { * * *  ***  * * *  ***   TICIdentifierComment   ***  * * *  ***  * * *  }


  //the list of documentations for the parameters of a function or function
  //type
  TICNodeArray = array of TICNode;
  //the list of lists of documentation of additional attributes of identifiers
  //or files
  TAdditionalAttributeSections = array[1..AdditionalAttributeCount] of
                                 TICNCompound;

  {Represents the comment of an identifier or file already split up in the
   different sections. }
  TICIdentifierComment = class(TICDocComment)
  private
    //the main (general) documentation of the identifier or file
    FMainDocumentation: TICNode;

    //(maybe) a future extension, a short summary of the documentation
//    FSummary: TICNode;

    //list of documentations of the parameters if a function or function type
    //is documented
    FParameters: TICNodeArray;
    //documentation of the return value/result if a function or function type
    //is documented
    FReturnValue: TICNode;
    //the list of exceptions that may be raised/thrown by the function or by
    //functions of the function type;
    //the child nodes are of type ~[link TICNExceptionSection]
    FExceptions: TICNCompound;
    //the list of identifiers or files to emphasize the relationship with,
    //preferably with a link to it
    //the child nodes are of type ~[link TICNSeeSection]
    FSeeIdentifiers: TICNCompound;
    //the list of additional sources of information about the identifier or
    //file
    FSeeTexts: TICNCompound;
    //the (list of) reason(s) why the identifier or file is deprecated
    FDeprecateds: TICNCompound;
    //the list of things still to be done for the identifier or file,
    //what's still missing
    FToDos: TICNCompound;
    //the list of features that can still be added
    FFeatures: TICNCompound;
    //the list of examples on how to use the identifier
    FExamples: TICNCompound;
    //the (list of) author(s) who worked on the identifier or file
    FAuthors: TICNCompound;
    //the version of the identifier or file, or the list of versions with an
    //explanation of the changes in each one
    FVersions: TICNCompound;
    //the lists of additional attributes of the identifier or file
    FAdditionalAttributes: TAdditionalAttributeSections;

    //a list of labels that mark the identifier or file to be excluded;~[br]
    //if this list is not empty, the identifier or file should be excluded by
    //default;~[br]
    //an empty label - i.e. ~[code ''] - is also allowed;
    //~todo not yet used/implemented
    //~todo sorted?
    //~see UJADDComments.TJaddSourceComments.TransformComment
    //     (unless implemented)
    FExcludeLabels: TStringList;
  public
    //Creates the object to hold the comment of an identifier or file.
    constructor Create;
    //Creates the object to hold the comment of an identifier with the
    //specified numbers of parameters (for functions/function types).
    constructor CreateWithParams(ParamNum: Integer);
    //Frees the comment and the object.
    destructor Destroy; override;


    property MainDocumentation: TICNode read FMainDocumentation
                                        write FMainDocumentation;
//    property Summary: TICNode read FSummary write FSummary;
    property Parameters: TICNodeArray read FParameters;
    property ReturnValue: TICNode read FReturnValue write FReturnValue;
    property Exceptions: TICNCompound read FExceptions;
    property SeeIdentifiers: TICNCompound read FSeeIdentifiers;
    property SeeTexts: TICNCompound read FSeeTexts;
    property Deprecateds: TICNCompound read FDeprecateds;
    property ToDos: TICNCompound read FToDos;
    property Features: TICNCompound read FFeatures;
    property Examples: TICNCompound read FExamples;
    property Authors: TICNCompound read FAuthors;
    property Versions: TICNCompound read FVersions;
    property AdditionalAttributes: TAdditionalAttributeSections
                                                    read FAdditionalAttributes;

    property ExcludeLabels: TStringList read FExcludeLabels;
  end;





   { * * *  ***  * * *  ***   TICUserDocComment   ***  * * *  ***  * * *  }


  {Represents a page/topic of additional user documentation }
  TICUserDocComment = class(TICSimpleComment)
  private
    //the internal name of the page/topic, used to create links to it
    FTopicName: String;
    //the title of the page/topic
    FTitle: String;

  public

    property TopicName: String read FTopicName write FTopicName;
    property Title: String read FTitle write FTitle;
  end;



   { * * *  ***  * * *  ***   TICGUIHelpComment   ***  * * *  ***  * * *  }

  {Represents documentation as a help on a GUI (a form).
  TICGUIHelpComment = class(TICDocComment)
  private
  public
    property GUIAliases: TStrings;
    property GUIManualLinks: TList;
    property GUITopics: TICNCompound;
  end;
}





   { * * *  ***  * * *  ***   TICIdentifierComments   ***  * * *  ***  * * *  }


  {Nomen est Omen. This is a simple adapter, adapting a list of identifiers to
   the "interface" as used by ~[link TStaticKeyMapTemplate]. As
   TStaticKeyMapTemplate is a template, there is no real interface declared,
   only the ~[link .Count] and ~[link .IndexOf] methods have to be defined. }
  TIdentifierListAdapter = class
  private
    //the list of identifiers that is adapted for the map
    FList: TIdentifierList;
  public
    //Creates the adapter object for the list.
    constructor Create(List: TIdentifierList);

    //Returns the index of the identifier (of the key).
    function IndexOf(Identifier: TIdentifier): Integer;
    //Returns the number of identifiers (of keys).
    function Count: Integer;
  end;



  //a map from identifiers to their comments
  TICIdentifierComments = class;


  {The documentation for identifiers. }
  TIdentifierCommentValue = record
    //the comment of the identifier
    Comment: TICIdentifierComment;
    //the assembled final documentation of the identifier
    FinalComment: TICSimpleComment;
    //if available, the documentation of the members of the idenfifier(/class)
    Members: TICIdentifierComments;
  end;



{$DEFINE StaticKeyMapTemplateDoNotEndType}
{$UNDEF StaticKeyMapTemplateFreeKeyList}
{$UNDEF StaticKeyMapTemplateValueIsObject}
{$DEFINE StaticKeyMapTemplateInitializeItems}
{$UNDEF StaticKeyMapTemplateValueFree}

  //the keys for the template map to use
  TStaticKeyMapTemplateKey = TIdentifier;
  //the list of keys for the template map to use
  TStaticKeyMapTemplateKeys = TIdentifierListAdapter;
  //the values for the template map to use
  TStaticKeyMapTemplateValue = TIdentifierCommentValue;

{$INCLUDE ..\..\General\Templates\StaticKeyMapTemplate.inc}

  //a map from identifiers to their comments
  TICIdentifierComments
{$INCLUDE ..\..\General\Templates\StaticKeyMapTemplate.inc}

  public
    //Free all items and if applicable the keys list.
    destructor Destroy; override;
  end;

  //alias for the map to be used by the implementations of the methods
  TStaticKeyMapTemplate = TICIdentifierComments;






type

   { * * *  ***  * * *  ***   TICComments   ***  * * *  ***  * * *  }


  //the base class of all classes holding a list of comments/parts of
  //documentation
  TICComments = class;


  {The type of call back procedures to be called for each comment/part of
   documentation.
  ~param Comment each comment/part of documentation
  ~param Sender  the list of comments/parts of documentations that's calling
                 the procedure }
  TICCommentsCallBackProc = procedure (Comment: TICDocComment;
                                       Sender: TICComments) of object;

  {The base class of all classes holding a list of comments/parts of
   documentation. It holds a reference on the generator and defines a way to
   call a procedure for every stored comment/part of documentation in it. }
  TICComments = class
  private
    //the generator for which the comments are stored
    FGenerator: TMakeDoc;
  public
    //Creates the object and saves the reference to the generator.
    constructor Create(Generator: TMakeDoc);

    {Calls the procedure with every stored comment/part of the documentation.
    ~param CallBack the procedure to call for each stored comment }
    procedure ForEach(CallBack: TICCommentsCallBackProc); virtual; abstract;

    property Generator: TMakeDoc read FGenerator;
  end;






   { * * *  ***  * * *  ***   TICSourceComments   ***  * * *  ***  * * *  }


  //the class holding the list of comments/documentation for each identifier
  //and file
  TICSourceComments = class;

  {The documentation for files. }
  TICFileComments = record
    //the comment of the file
    FileComment: TICIdentifierComment;
    //the assembled final documentation of the file
    FinalComment: TICSimpleComment;
    //the documentation of all identifiers declared inside the file
    IdentifierComments: TICIdentifierComments;
  end;

  //the list of documentation for all parsed files
  TAllICFileComments = array of TICFileComments;



  {Called for every comment belonging to an identifier (or file).
  ~param Comment    the comment of the identifier or file
  ~param Identifier the identifier the comment belongs to, nil if of a file
  ~param TheFile    the file the comment belongs to, nil if of an identifier
  ~param Sender     the list of comments containing the comment }
  TICIdentCommentsCallBackProc = procedure (Comment: TICIdentifierComment;
                                            Identifier: TIdentifier;
                                            TheFile: TPascalFile;
                                            Sender: TICSourceComments) of
                                                                        object;


  {The class holding the list of comments/documentation for each identifier
   and file. It defines additional access functions to the comments and final
   documentations as well as as a method to call a procedure for every
   identifier and file with their documentation.

   Another test for this program: