uicidentdocbuilder.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 UICIdentDocBuilder;

{Contains the class ~[linkClass TICIdentDocBuilder] which will be used to build
 the documentation of each identifier and file.
}

interface


uses UBaseIdents, UExtIdents,
     UOptions, UGenerationMessages,
     UICDocumentDoc,
     UICNodes,
     UILComment,
     UICDeclarationAssembler;


type

  //the messages that can be generated when the documentation for the
  //identifiers and files is generated
  TIdentDocBuilderMessages = (
                              //no parameter of the function has been
                              //documented
                              idbmNoParameterDocumented,
                              //at least one parameter of a function is not
                              //documented
                              idbmAtLeastOneParameterUndocumented,
                              //result of function not documented
                              idbmResultNotDocumented,
                              //~~result or ~~exception found, but identifier
                              //is not a function or function type
                              idbmFunctionSectionDocumentedButNotAFunction,

                              //the implemented interface redirected to a
                              //property wasn't found in the list of
                              //implemented interfaces by the class
                              idbmImplementedInterfaceOfPropertyDoesNotMatch,
                              //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
                              idbmInterfaceOfMethodNotImplemented
                              );



  //type to filter some sections of the comments
  TCommentsSectionsFilter = (
                             //don't include the sections with links to other
                             //identifiers or files
                             csfSee,
                             //don't inlude the section which refer to
                             //further documentation
                             csfSeeText,
                             //don't show, that identifiers or files are
                             //deprecated
                             csfDeprecated,
                             //don't show, that identifiers or files are
                             //unfinished and some things still have to be done
                             csfToDo,
                             //don't show, that identifiers or files are
                             //missing some features
                             csfFeature,
                             //don't show the author(s) of identifiers and
                             //files
                             csfAuthor,
                             //don't show the versions(s) of identifiers and
                             //files
                             csfVersion,
                             //don't show additional attributes of identifiers
                             //and files
                             csfAdditionals,
                             //don't show examples on how to use identifiers
                             csfExamples);



  //type to filter some sections of the documentation of an identifier
  TIdentifierSectionsFilter = (
                               //don't list the parameters of functions or
                               //functions types
                               isfParameter,
                               //don't list the result of functions or
                               //functions types
                               isfResult,
                               //don't list the exceptions raised by functions
                               //or functions types
                               isfException,

                               //don't list the identifiers using this one
                               isfUsedBy,
                               //don't list the functions calling this one
                               isfCalledBy,
                               //don't list the identifiers used by this
                               isfGlobals,                 //function
                               //don't list the functions used by this function
                               isfCalls,
                               //don't show the function that is overridden
                               isfOverrides,               //one
                               //don't show the functions that override this
                               isfOverriddenBy);           //one


  //type to filter some sections of the documentation of a file
  TFileSectionsFilter = (
                         //don't list the units used by the file
                         fsfUsesUnits,
                         //don't list the files using this unit
                         fsfUsedBy,
                         //don't list the units included in this package
                         fsfRequires,
                         //don't list the identifiers exported in/by this file
                         fsfExporteds,
                         //don't show the parameters of the program (they are
                         //not used anymore)
                         fsfProgramParameters);






  //the class of classes that can build the documentation of an identifier
  //or file
  TICIdentDocBuilderClass = class of TICIdentDocBuilder;





   { * * *  ***  * * *  ***   TICIdentDocBuilder   ***  * * *  ***  * * *  }


  {The base and currently only class used to build the documentation of each
   identifier and file from their comments and any other available information.
   The documentation is still expressed in nodes of the general
   ~[linkUnit UICNodes COM] - Comment Object Model.

  A simple test again: ~[defineText blubblab ~[link GetOptionCount] test] }
  TICIdentDocBuilder = class
  private
    //reference to the generator is for:
    //general:              DoNotDocumentIdentifier, AddMessages
    //exports declarations: FindIdentifier, AddExpression
    //identifiers:          TICDeclarationAssembler
    //maybe it should be removed,
    //only DoNotDocumentIdentifier and AddMessages are really needed

    //the generator for which the documentation is generated
    //~todo maybe remove the reference
    FGenerator: TICDocumentDoc;

    //ID of the messages of this class
    FIdentDocBuilderMessagesID: TMessageID;

    //an object to access the options of the builder of documentation for
    //identifiers and files through a more general interface
    FOptionAccessor: TOptionWrapper;


    //filter some sections of the documentation of an identifier or file
    FCommentsSectionsFilter: set of TCommentsSectionsFilter;
    //filter some sections of the documentation of an identifier
    FIdentifierSectionsFilter: set of TIdentifierSectionsFilter;
    //filter some sections of the documentation of a file
    FFileSectionsFilter: set of TFileSectionsFilter;

{
    //filter some sections of the documentation (mostly lists)
    FDocumentationSectionsFilter: TDocumentationSectionsFilters;
}

    //still generate list of parameters even when no one has been documented?
    FParameterListIfUncommented: Boolean;
    //still generate entry for the result/return type of function and function
    //typen even when it has not been documented?
    FResultIfUncommented: Boolean;


    //Called when a reference to an implemented interface is found in the
    //declaration but the interface has not been implemented by the class.
    procedure HandleUnknownInterface(Sender: TICDeclarationAssembler;
                                     const InterfaceName: String;
                                     Position: TIdentifier; 
                                     FromMethod: Boolean);
  protected

    //Adds the message to the geneator.
    procedure AddMessage(Msg: TIdentDocBuilderMessages; const Text: String;
                         Identifier: TIdentifier; TheFile: TPascalFile);


    //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 a link to the given identifier/file.
    procedure AddFileLink(TheFile: TPascalFile; AddTo: TICNCompound);
    //Adds a link to the given identifier/file.
    procedure AddIdentifierLink(Ident: TIdentifier; AddTo: TICNCompound;
                                AddLinkToFile: Boolean = False);
    //Adds a link to the given identifier inside a record-like type.
    procedure AddRecordFieldLink(Ident: TIdentifier; AddTo: TICNCompound;
                                 AddRecordLink: Boolean = False);






    //Adds the list of all implemented interfaces.
    function AddInterfaceLinks(Ident: TRecordType; First: Boolean;
                               AddTo: TICNCompound): Boolean;
    //Adds the list of all in parent-classes implemented interfaces.
    procedure AddParentInterfaceLinks(Ident: TRecordType;
                                      AddTo: TICNCompound);
    //Adds the list of the direct descendants of the record-like type.
    procedure AddDirectDescendantList(Ident: TRecordType; AddTo: TICNCompound);
    //Adds the list of the classes implementing the interface.
    procedure AddImplementingClassesList(Ident: TRecordType;
                                         AddTo: TICNCompound);
    //Gets the list of documented methods overriding the method.
    procedure GetOverridingMethods(Method: TFunction; RecType: TRecordType;
                                   List: TIdentifierList);
    //Adds the list of links to the methods overriding the given one.
    procedure AddOverridingMethods(Method: TFunction; RecType: TRecordType;
                                   AddTo: TICNCompound);
    //Adds a list of all abstract methods in the class.
    procedure AddStillAbstractMethods(AClass: TRecordType;
                                      AddTo: TICNCompound);


    //Adds the inheritance list of the record-like type.
    procedure AddAncestorList(Ident: TRecordType; AddTo: TICNCompound);


    //Adds a list of the identifiers as part of the documentation.
    procedure AddDocumentationList(List: TIdentifierList; SortTo: TRecordType;
                                   Kind: TICTopicForIdentifier;
                                   AddTo: TICNCompound);
    //Adds the list of global identifiers used in the function.
    procedure AddFunctionGlobals(Identifier: TFunction; AddTo: TICNCompound);
    //Adds the list of all identifiers using the identifier.
    procedure AddUsedBy(Identifier: TIdentifier; AddTo: TICNCompound);









    //Handles the ~~deprecated, ~~todo and ~~feature sections of comments and
    //adds their documentation.
    procedure AddSpecials(Comment: TICIdentifierComment; AddTo: TICNCompound);

    //Handles the ~~see and ~~seeText sections of comments and adds their
    //documentation.
    procedure AddSeeComment(Comment: TICIdentifierComment;
                            AddTo: TICNCompound);
    //Handles the ~~author and ~~version sections and the other additional
    //attributes of comments and adds their documentation.
    function AddAuthorVersionAdditionals(Comment: TICIdentifierComment;
                                         AddTo: TICNCompound): TICNCompound;
    //Adds the documentation of examples in comments.
    procedure AddExamples(Comment: TICIdentifierComment;
                          AddTo: TICNCompound);





    //Adds the parameters of the program.
    procedure AddProgramParameters(ProgramFile: TPascalFile;
                                   AddTo: TICNCompound);
    //Adds the list of all required packages.
    procedure AddRequiredPackages(PackageFile: TPascalFile;
                                  AddTo: TICNCompound);
    //Adds the text of an exported function/identifier.
    procedure AddExportsDeclaration(Ident: TExportIdentifier;
                                    AddTo: TICNCompound);
    //Adds the list of all exported functions/identifiers.
    procedure AddExports(AFile: TPascalFile; AddTo: TICNCompound);
    //Adds the list of all used/contained units in a part.
    procedure AddUnitList(ForFile: TPascalFile; FilePart: TFilePart;
                          AddTo: TICNCompound);

    //Adds the lists of files using the file.
    procedure AddUsingFiles(AFile: TPascalFile; AddTo: TICNCompound);




    //Handles the parameters and the result of functions and function types.
    procedure HandleFunctionParamAndResult(Comment: TICIdentifierComment;
                                           Params: TIdentifierList;
                                           IsFunction: Boolean;
                                           AddTo: TICNCompound;
                                           Identifier: TIdentifier);
    //Generates the special documentation of a function.
    procedure HandleFunction(Comment: TICIdentifierComment;
                             Identifier: TFunction;
                             AddTo: TICNCompound);