uilcomment.pas

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

   CODE: ~[code some Code with an [ array ] ] <- this one is not as code

   A: ~[link FComments]

   B: ~[link Self.Generator.Progress]

   B: ~[link FGenerator.Progress]

   B: ~[link Generator.Progress]

   C: ~[link FComments.FileComment]

   D: ~[link FComments[0].FileComment]
      <- this one seems strangly formatted in the output but is correct

   D: ~[link FComments~[[0~[].FileComment]
   }
  TICSourceComments = class(TICComments)
  private
    //the comments of all the files and identifiers
    FComments: TAllICFileComments;

    //Gets the map containing the comment and documentation for each member of
    //the identifier.
    function GetMap(Comments: TICIdentifierComments;
                    Identifier: TIdentifier): TICIdentifierComments;


    //Gets the comment of the identifier.
    function GetICComment(Identifier: TIdentifier): TICIdentifierComment;
    //Gets the comment of the file.
    function GetICFileComment(AFile: TPascalFile): TICIdentifierComment;

    //Gets the final comment, the documentation, of the identifier.
    function GetFinalICComment(Identifier: TIdentifier): TICSimpleComment;
    //Gets the final comment, the documentation, of the file.
    function GetFinalICFileComment(AFile: TPascalFile): TICSimpleComment;

    //Sets the final comment, the documentation, of the identifier.
    procedure SetFinalICComment(Identifier: TIdentifier;
                                Value: TICSimpleComment);
    //Sets the final comment, the documentation, of the file.
    procedure SetFinalICFileComment(AFile: TPascalFile;
                                    Value: TICSimpleComment);


    //Creates a mapping to empty comments and documentation for each identifier
    //and file.
    procedure CreateEmptyComments;
  public
    //Creates the object to hold the comments and documentation for each
    //identifier and file.
    constructor Create(Generator: TMakeDoc);
    //Frees the object and all comments.
    destructor Destroy; override;

    //Calls the procedure with every stored comment/part of the documentation.
    procedure ForEach(CallBack: TICCommentsCallBackProc); override;
    //Calls the procedure for each file and identifier with their comments.
    procedure ForEachIdentComment(CallBack: TICIdentCommentsCallBackProc);


    property Comment[Identifier: TIdentifier]: TICIdentifierComment
                                                             read GetICComment;
    property FileComment[AFile: TPascalFile]: TICIdentifierComment
                                                         read GetICFileComment;


    property FinalComment[Identifier: TIdentifier]: TICSimpleComment
                                read GetFinalICComment write SetFinalICComment;
    property FinalFileComment[AFile: TPascalFile]: TICSimpleComment
                        read GetFinalICFileComment write SetFinalICFileComment;
  end;









   { * * *  ***  * * *  ***   TICUserDocComments   ***  * * *  ***  * * *  }


  //the class holding the additional user documentation as a list of
  //pages/topics
  TICUserDocComments = class;

  {Called for every comment of the additional user documentation.
  ~param Comment the comment of the page/topic
  ~param Sender  the list of comments containing the comment }
  TICUserCommentsCallBackProc = procedure (Comment: TICUserDocComment;
                                           Sender: TICUserDocComments) of
                                                                        object;


  {The class holding the additional user documentation as a list of
   pages/topics. It defines an additional access functions to the pages as well
   as as a method to call a procedure for every page. }
  TICUserDocComments = class(TICComments)
  private
    //list of the ~[linkClass TICUserDocComment comments] of the pages
    FComments: TList;

    //strings are short, unique names of files, objects are index of first
    //page, list is not sorted, entries are in the same order they were added;
    //it is used only to get the file of a page
    FFiles: TStringList;

    //the additional text for the index of the documentation
    FIndexComment: TICSimpleComment;

    //Gets the comment of the page.
    function GetComment(PageIndex: Integer): TICUserDocComment;
  public
    //Creates the object to hold the additional documentation.
    constructor Create(Generator: TMakeDoc);
    //Frees the object and all comments.
    destructor Destroy; override;


    //Called to create a new page of user documentation.
    function AddPage(NewPageIndex: Integer): TICUserDocComment;
    //Sets the list of files containing the pages.
    procedure SetFileList(FileList: TStringList);

    //Returns the (short unique) name of the file containing the page.
    function FileOfPage(PageIndex: Integer): String;


    //Calls the procedure with every stored comment/part of the documentation.
    procedure ForEach(CallBack: TICCommentsCallBackProc); override;
    //Calls the procedure with every page of user documentation.
    procedure ForEachUserComment(CallBack: TICUserCommentsCallBackProc);

    //Returns the number of pages/topics with additional user documentation.
    function PageCount: Integer;

    property Comment[PageIndex: Integer]: TICUserDocComment read GetComment;

    property IndexComment: TICSimpleComment read FIndexComment;
  end;









implementation



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


{Creates the object. }
constructor TICDocComment.Create;
begin
 inherited Create;                     //create the object

 FNodeOwner := TICNodeOwner.Create;    //create object to "own" the nodes
 FKeyWords := TStringList.Create;      //create list of key words
end;

{Frees the comments and the object. }
destructor TICDocComment.Destroy;
begin
 FNodeOwner.Free;                      //free the owner of nodes and all nodes
 FKeyWords.Free;                       //free list of key words

 inherited Destroy;                    //free the object
end;




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

{Creates the object. }
constructor TICSimpleComment.Create;
begin
 inherited Create;                                   //create the object

 FContent := TICNCompound.CreateCompound(NodeOwner); //create empty comment
end;








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

{Creates the object to hold the comment of an identifier or file. }
constructor TICIdentifierComment.Create;
var         i           :Integer;  //counter through the additional attributes
begin
 inherited Create;                 //create the object

 //create the lists to hold the different special comments
 FExceptions := TICNCompound.CreateCompound(NodeOwner);
 FSeeIdentifiers := TICNCompound.CreateCompound(NodeOwner);
 FSeeTexts := TICNCompound.CreateCompound(NodeOwner);
 FDeprecateds := TICNCompound.CreateCompound(NodeOwner);
 FToDos := TICNCompound.CreateCompound(NodeOwner);
 FFeatures := TICNCompound.CreateCompound(NodeOwner);
 FExamples := TICNCompound.CreateCompound(NodeOwner);
 FAuthors := TICNCompound.CreateCompound(NodeOwner);
 FVersions := TICNCompound.CreateCompound(NodeOwner);
 for i := Low(FAdditionalAttributes) to High(FAdditionalAttributes) do
  FAdditionalAttributes[i] := TICNCompound.CreateCompound(NodeOwner);

 //create list to hold labels by which the identifier should be excluded
 FExcludeLabels := TStringList.Create;
 //FExcludeLabels.Sorted := True;
 ///FExcludeLabels.Duplicates := dupIgnore;
end;


{Creates the object to hold the comment of an identifier with the specified
 numbers of parameters (for functions/function types).
~param ParamNum the number of parameters the function or functiony type has;
                has to be 0 for any other kind of identifier }
constructor TICIdentifierComment.CreateWithParams(ParamNum: Integer);
begin
 Create;                                //create the object

 SetLength(FParameters, ParamNum);      //get room for comments on parameters
end;

{Frees the comment and the object. }
destructor TICIdentifierComment.Destroy;
begin
 FExcludeLabels.Free;                   //free list of exclude labels

 inherited Destroy;                     //free the object
end;






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


{Creates the adapter object for the list.
~param List the list of identifiers to adapt as a list of keys }
constructor TIdentifierListAdapter.Create(List: TIdentifierList);
begin
 inherited Create;               //create the object
 FList := List;                  //save the list
end;

{Returns the index of the identifier (of the key). The identifier should be in
 the list.
~param Identifier the identifier to determine the index of in the list
~result the index of the identifier in the list; -1 if not in the list }
function TIdentifierListAdapter.IndexOf(Identifier: TIdentifier): Integer;
begin
 Result := FList.FindIdentIndex(Identifier);  //return index of the identifier
end;

{Returns the number of identifiers (of keys).
~result the number of identifiers in the list }
function TIdentifierListAdapter.Count: Integer;
begin
 Result := FList.Count;                       //return number of identifiers
end;





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


{Free all items and if applicable the keys list. }
destructor TICIdentifierComments.Destroy;
var        i                    :Integer;     //counter through all items
begin
 FKeys.Free;                                  //free the keys

 for i := 0 to Length(FValues) - 1 do         //free each item/value
  begin
   FValues[i].Comment.Free;
   FValues[i].FinalComment.Free;
   FValues[i].Members.Free;
  end;

 inherited Destroy;                           //free the map
end;









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

{Creates the object and saves the reference to the generator.
~param Generator the generator for which the comments are stored }
constructor TICComments.Create(Generator: TMakeDoc);
begin
 inherited Create;                      //create the object

 FGenerator := Generator;               //save the reference to the generator
end;





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

{Creates the object to hold the comments and documentation for each identifier
 and file.
~param Generator the generator for which the comments are stored }
constructor TICSourceComments.Create(Generator: TMakeDoc);
begin
 inherited Create(Generator);          //create the object

 //create empty comments for each file and identifier
 CreateEmptyComments;
end;

{Frees the object and all comments. }
destructor TICSourceComments.Destroy;
var        i                :Integer;      //counter through all files
begin
 for i := 0 to Length(FComments) - 1 do    //for each file
  begin
   FComments[i].FileComment.Free;            //free its comment
   FComments[i].FinalComment.Free;           //free its documentation
   FComments[i].IdentifierComments.Free;     //free comments of its identifiers
  end;

 inherited Destroy;                        //free the object
end;


{Creates a mapping to empty comments and documentation for each identifier and
 file. }
procedure TICSourceComments.CreateEmptyComments;

 {Fills the mapping for each identifier in the list to empty comments and
  documentation. For each record-like type an additional mapping for its
  members is created, too.
 ~param Map         the mapping to fill
 ~param Identifiers the list of identifiers to create the mapping for }
 procedure CreateAllComments(Map: TICIdentifierComments;
                             Identifiers: TIdentifierList);
 var       i                :Integer;             //counter through identifiers
           Identifier       :TIdentifier;         //each identifier
           //the value mapped to by the identifier
           Value            :TIdentifierCommentValue;
           //number of parameters for the identifier
           ParamNum         :Integer;
           //adapter from the list of members to a list of keys
           IdentList        :TIdentifierListAdapter;
 begin
  for i := 0 to Identifiers.Count - 1 do //for each identifier
   begin
    Identifier := Identifiers[i];          //get the identifier

    ParamNum := 0;                         //assume no parameters
    if Identifier is TFunction then        //get number of parameters
     ParamNum := TFunction(Identifier).Params.Count
    else
     if Identifier is TFunctionType then
      ParamNum := TFunctionType(Identifier).Params.Count;

    Value.Members := nil;                  //assume it has no members
    //create the empty comment for the identifier
    Value.Comment := TICIdentifierComment.CreateWithParams(ParamNum);
    try
      if Identifier is TRecordType then    //it might have some members?