uicidentdocbuilder.pas

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

    //Generates the special documentation of a function type.
    procedure HandleFunctionType(Comment: TICIdentifierComment;
                                 Identifier: TFunctionType;
                                 AddTo: TICNCompound);



    //Handles and adds the documentation of the identifier.
    procedure AddIdentifierComment(Identifier: TIdentifier;
                                   Comment: TICIdentifierComment;
                                   Destination: TICSimpleComment;
                                   MainNode: TICNCompound);

    //Makes sure no invalid sections are in the documentation.
    procedure CheckNoFunctionSections(Comment: TICIdentifierComment;
                                      ForIdentifier: TIdentifier;
                                      ForFile: TPascalFile);
  public
    //Creates the builder, saves the generator and registers its messages.
    constructor Create(Generator: TICDocumentDoc);
    //Unregisters the messages and frees the object and the accessor of
    //options.
    destructor Destroy; override;



    //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; Value: TOptionValue); virtual;


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



    //Resets the builder of documentation to generate new documentation.
    procedure ResetForNewGeneration;



    //Generates the documentation for the simple identifier.
    procedure GetIdentifierComment(Identifier: TIdentifier;
                                   Comment: TICIdentifierComment;
                                   Destination: TICSimpleComment);
    //Generates the documentation for the file.
    procedure GetFileComment(TheFile: TPascalFile;
                             Comment: TICIdentifierComment;
                             Destination: TICSimpleComment);
    //Generates the documentation for the record-like type.
    procedure GetClassComment(Identifier: TRecordType;
                              Comment: TICIdentifierComment;
                              Destination: TICSimpleComment);
  end;









implementation

uses SysUtils, Classes,
     UPascalConsts,
     UTokenParser,
     UDocumentationTexts;






   { * *  ***  *  ***   TICIdentDocBuilderOptionWrapper   ***  *  ***  * *  }

type

  {Allows editing of the options of the builder of documentation about
   identifiers and files by wrapping it to the defined interface. }
  TICIdentDocBuilderOptionWrapper = class(TOptionWrapper)
  private
    //the builder of documentation about identifiers and files to wrap to allow
    //its options to be used
    FICIdentDocBuilder: TICIdentDocBuilder;
  protected
    //Returns the current class if the options are loaded in a hierarchy.
    function GetStartClass: TClass; override;

    //Gets the value of an option.
    function GetOption(Index: Cardinal): TOptionValue; override;
    //Sets the value of an option.
    procedure SetOption(Index: Cardinal; const Value: TOptionValue); override;
  public
    //Creates wrapper and saves the reference to the builder of documentation.
    constructor Create(ICIdentDocBuilder: TICIdentDocBuilder);

    //Returns the number of available options.
    function Count: Cardinal; override;
    //Gets a description of an option.
    procedure Description(Index: Cardinal;
                          var Desc: TOptionDescription); override;

    //Gets the topic of an option.
    function Topic(Index: Cardinal): String; override;
  end;




   { * *  ***  *  ***   TICIdentDocBuilderOptionWrapper   ***  *  ***  * *  }


{Creates the wrapper and saves the reference to the generator of documentation.
~param ICIdentDocBuilder the builder of documentation whose options should be
                         edited }
constructor TICIdentDocBuilderOptionWrapper.Create(ICIdentDocBuilder:
                                                           TICIdentDocBuilder);
begin
 inherited Create;                        //create the object

 FBaseClass := TICIdentDocBuilder;        //set (base) class of all builders

 FICIdentDocBuilder := ICIdentDocBuilder; //save the reference on the builder
end;


{Returns the number of available options.
~result the number of available options }
function TICIdentDocBuilderOptionWrapper.Count: Cardinal;
begin //return number of options of parser
 Result := FICIdentDocBuilder.GetOptionCount;
end;

{Gets a description of an option.
~param Index index of the option to get data of
~param Desc  out: the description of the option (name, type, default value,
                  etc.) }
procedure TICIdentDocBuilderOptionWrapper.Description(Index: Cardinal;
                                                 var Desc: TOptionDescription);
begin //get description from builder
 FICIdentDocBuilder.GetOptionDescription(Index, Desc);
end;


{Returns the current class if the options are loaded in a hierarchy.
~result the actual class }
function TICIdentDocBuilderOptionWrapper.GetStartClass: TClass;
begin
 Result := FICIdentDocBuilder.ClassType;
end;


{Gets the value of an option. Call ~[link Description] to get the type and
 the meaning of the option.
~param Index index of the option to get the value of
~result the value of the option }
function TICIdentDocBuilderOptionWrapper.GetOption(Index: Cardinal):
                                                                  TOptionValue;
begin
 Result := FICIdentDocBuilder.GetOption(Index); //get the option of the builder
end;

{Sets the value of an option. Call ~[link Description] to get the type and
 the meaning of the option.
~param Index index of the option to set the value
~param Value the new value of the option}
procedure TICIdentDocBuilderOptionWrapper.SetOption(Index: Cardinal;
                                                    const Value: TOptionValue);
begin
 FICIdentDocBuilder.SetOption(Index, Value);    //set the option of the builder
end;


{Gets the topic of an option, the name of the class of the builder the option
 is defined in.
~param Index index of the option to get the topic of
~result the topic of the option }
function TICIdentDocBuilderOptionWrapper.Topic(Index: Cardinal): String;
var      AClass         :TICIdentDocBuilderClass; //runner through all classes
begin
 if Index >= FICIdentDocBuilder.GetOptionCount then
  raise EInvalidOption.Create('Invalid index for option supplied!');

 //get the parent class of the evaluator introducing the option
 AClass := TICIdentDocBuilderClass(FICIdentDocBuilder.ClassType);
 while (AClass <> TICIdentDocBuilder) and
       (TICIdentDocBuilderClass(AClass.ClassParent).GetOptionCount > Index) do
  AClass := TICIdentDocBuilderClass(AClass.ClassParent);

 Result := AClass.ClassName;                      //return name of the class
end;























    //list for the option "CommentsSectionsFilter" of the builder of
    //documentation - ~[link TICIdentDocBuilder]
var OptionItemsCommentsSectionsFilter: TStringList = nil;
    //list for the option "IdentifierSectionsFilter" of the builder of
    //documentation - ~[link TICIdentDocBuilder]
    OptionItemsIdentifierSectionsFilter: TStringList = nil;
    //list for the option "FileSectionsFilter" of the builder of
    //documentation - ~[link TICIdentDocBuilder]
    OptionItemsFileSectionsFilter: TStringList = nil;



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


    //the descriptions of messages that can be added in the class
    //~[link TICIdentDocBuilder]
var IdentDocBuilderMessageDescriptions: TMessageDescriptions = nil;


{Creates the builder, saves the generator and registers its messages.

 ~[defineText blubblab2 ~[link GetOptionCount] test]
~param Generator the generator for which the documentation is generated }
constructor TICIdentDocBuilder.Create(Generator: TICDocumentDoc);
begin
 inherited Create;                    //create the object

 FGenerator := Generator;             //save the reference on the generator

 //register messages of this class
 FIdentDocBuilderMessagesID := Generator.RegisterMessages(
                                           IdentDocBuilderMessageDescriptions);
end;

{Unregisters the messages and frees the object and the accessor of options.

 ~[insertText blubblab2 test2 ~[link GetOptionDescription] foobar]}
destructor TICIdentDocBuilder.Destroy;
begin
 FOptionAccessor.Free;                //free accessor of the option

 if Assigned(FGenerator) then
  //unregister messages of this class
  FGenerator.UnRegisterMessages(FIdentDocBuilderMessagesID);

 inherited Destroy;                   //free the object
end;








{Returns the number of available options in generators of this class.
~result the number of available options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function TICIdentDocBuilder.GetOptionCount: Cardinal;
begin
 Result := 5;
end;


{Gets a description of an option.
~param Index index of the option to get data of
~param Desc  out: the description of the option (name, type, default value,
                  etc.)
~see GetOptionCount }
class procedure TICIdentDocBuilder.GetOptionDescription(Index: Cardinal;
                                                 var Desc: TOptionDescription);
begin
 ClearDescription(Desc);               //clear structure
 case Index of                         //depending on index of option
   0:  begin                             //set the values describing the option
        Desc.Name := 'CommentsSectionsFilter';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'Filters some sections of the comments of identifiers and files.';
        Desc.DataType := otSet;
        Desc.SetNames := OptionItemsCommentsSectionsFilter;
       end;
   1:  begin
        Desc.Name := 'IdentifierSectionsFilter';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'Filters some sections of the documentation of an identifier.';
        Desc.DataType := otSet;
        Desc.SetNames := OptionItemsIdentifierSectionsFilter;
       end;
   2:  begin
        Desc.Name := 'FileSectionsFilter';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'Filters some sections of the documentation of a file.';
        Desc.DataType := otSet;
        Desc.SetNames := OptionItemsFileSectionsFilter;
       end;
   3:  begin
        Desc.Name := 'ParameterListIfUncommented';
        Desc.Category := 'Comments';
        Desc.Description := 'Create a list for the documentation of the parameters even if none has been commented.';
        Desc.DataType := otBoolean;
        Desc.DefaultValue.BoolData := False;
       end;