uilcomment.pas

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

       begin
        //create an adapter for the members
        IdentList := TIdentifierListAdapter.Create(TRecordType(Identifier).
                                                                    IdentList);
        try
          //create map of comments for the members
          Value.Members := TICIdentifierComments.Create(IdentList);
        except
          IdentList.Free;
          raise;
        end;

        //create empty comments for all members
        CreateAllComments(Value.Members, TRecordType(Identifier).IdentList);
       end;

      Value.FinalComment := nil;           //no documentation assigned so far

      Map.Put(Identifier, Value);          //put the values for the identifiers
    except
      Value.Comment.Free;
      Value.Members.Free;

      raise;
    end;
   end; //for i := 0 to Identifiers.Count - 1
 end;

var       i                :Integer;                //counter through all files
          AFile            :TPascalFile;            //each file
          //adapter from the list of identifiers to a list of keys
          IdentList        :TIdentifierListAdapter;
begin
 SetLength(FComments, Generator.Files.Count);       //create the list
 if Length(FComments) > 0 then                      //some files available?
  begin
   //clear the list
   FillChar(FComments[0], Generator.Files.Count * SizeOf(FComments[0]), 0);

   for i := 0 to Length(FComments) - 1 do             //for each file
    begin
     AFile := Generator.Files[i];                       //get the file
     //create the empty comment for the file
     FComments[i].FileComment := TICIdentifierComment.Create;

     //create an adapter for the identifiers in the file
     IdentList := TIdentifierListAdapter.Create(AFile.Idents);
     try
       //create map of comments for the identifiers
       FComments[i].IdentifierComments := TICIdentifierComments.Create(
                                                                    IdentList);
     except
       IdentList.Free;
       raise;
     end;

     //no documentation for the file assigned so far
     FComments[i].FinalComment := nil;

     //create empty comments for all identifiers
     CreateAllComments(FComments[i].IdentifierComments, AFile.Idents);
    end;
  end;
end;



{Gets the map containing the comment and documentation for each member of the
 identifier.
~param Comments   the mapping containing the identifier itself or its class;
                  originally called with the list of identifiers directly in
                  the file
~param Identifier the identifier for which the mapping should be returned
~result the map containing the comment and documentation of the identifier }
function TICSourceComments.GetMap(Comments: TICIdentifierComments;
                               Identifier: TIdentifier): TICIdentifierComments;
begin
 assert(assigned(Comments));

 if assigned(Identifier.MemberOf) then             //is in a class?
  begin
   Comments := GetMap(Comments, Identifier.MemberOf); //get mapping of members
   assert(assigned(Comments));
  end;

 Result := Comments.Items[Identifier].Members;     //return mapping for members
 assert(assigned(Result));
end;


{Gets the comment of the identifier.
~param Identifier the identifier for which the comment should be returned
~result the comment of the identifier }
function TICSourceComments.GetICComment(Identifier: TIdentifier):
                                                          TICIdentifierComment;
var      i                :Integer;                //index of containing file
         Comments         :TICIdentifierComments;  //mapping containing comment
begin
 i := Generator.Files.IndexOf(Identifier.InFile);  //get index of file
 assert(i >= 0);

 Comments := FComments[i].IdentifierComments;      //get mapping of comments
 if assigned(Identifier.MemberOf) then             //is a member?
  Comments := GetMap(Comments, Identifier.MemberOf); //get mapping of member
 Result := Comments.Items[Identifier].Comment;     //return the comment
end;

{Gets the comment of the file.
~param AFile the file for which the comment should be returned
~result the comment of the file }
function TICSourceComments.GetICFileComment(AFile: TPascalFile):
                                                          TICIdentifierComment;
var      i                :Integer;     //index of the file
begin
 i := Generator.Files.IndexOf(AFile);   //get the index of the file
 assert(i >= 0);
 Result := FComments[i].FileComment;    //return comment of the file
end;

{Gets the final comment - the documentation - of the identifier.
~param Identifier the identifier for which the comment should be returned
~result the documentation of the identifier }
function TICSourceComments.GetFinalICComment(Identifier: TIdentifier):
                                                              TICSimpleComment;
var      i                :Integer;                //index of containing file
         Comments         :TICIdentifierComments;  //mapping containing comment
begin
 i := Generator.Files.IndexOf(Identifier.InFile);  //get index of file
 assert(i >= 0);

 Comments := FComments[i].IdentifierComments;      //get mapping of comments
 if assigned(Identifier.MemberOf) then             //is a member?
  Comments := GetMap(Comments, Identifier.MemberOf); //get mapping of member
 Result := Comments.Items[Identifier].FinalComment; //return the final comment
end;

{Gets the final comment - the documentation - of the file.
~param AFile the file for which the comment should be returned
~result the documentation of the file }
function TICSourceComments.GetFinalICFileComment(AFile: TPascalFile):
                                                              TICSimpleComment;
var      i                :Integer;     //index of the file
begin
 i := Generator.Files.IndexOf(AFile);   //get the index of the file
 assert(i >= 0);
 Result := FComments[i].FinalComment;   //return documentation of the file
end;

{Sets the final comment - the documentation - of the identifier.
~param Identifier the identifier for which the final comment should be set
~param Value      the documentation of the identifier }
procedure TICSourceComments.SetFinalICComment(Identifier: TIdentifier;
                                              Value: TICSimpleComment);
var       i                :Integer;               //index of containing file
          Comments         :TICIdentifierComments; //mapping containing comment
          Values           :TIdentifierCommentValue; //values of identifier
begin
 i := Generator.Files.IndexOf(Identifier.InFile);  //get index of file
 assert(i >= 0);

 Comments := FComments[i].IdentifierComments;      //get mapping of comments
 if assigned(Identifier.MemberOf) then             //is a member?
  Comments := GetMap(Comments, Identifier.MemberOf); //get mapping of member

 Values := Comments.Items[Identifier];             //get values of identifier
 Values.FinalComment := Value;                     //set the final comment
 Comments.Items[Identifier] := Values;             //set values of identifier
end;

{Sets the final comment - the documentation - of the file.
~param AFile the file for which the final comment should be set
~param Value the documentation of the file }
procedure TICSourceComments.SetFinalICFileComment(AFile: TPascalFile;
                                                  Value: TICSimpleComment);
var       i                :Integer;        //index of the file
begin
 i := Generator.Files.IndexOf(AFile);       //get the index of the file
 assert(i >= 0);
 FComments[i].FinalComment := Value;        //set documentation of the file
end;


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

 {Calls the procedure for each identifier in the list and for all members if an
  identifier is a record-like type.
 ~param Identifiers the list of identifiers to call the procedure with
 ~param Map         the comments of the identifiers }
 procedure ForEachIdentifier(Identifiers: TIdentifierList;
                             Map: TICIdentifierComments);
 var       i             :Integer;                //counter through identifiers
           Identifier    :TIdentifier;            //each identifier
           Comments      :TIdentifierCommentValue; //its comment values
 begin
  for i := 0 to Identifiers.Count - 1 do          //for each identifier
   begin
    Identifier := Identifiers[i];                   //get it
    Comments := Map.Items[Identifier];              //get its comment values
    CallBack(Comments.Comment, Self);               //call procecure for it

    if Identifier is TRecordType then               //is a record-like type?
     //call procedure for its members
     ForEachIdentifier(TRecordType(Identifier).IdentList, Comments.Members);
   end;
 end;

var       i                  :Integer;      //counter through all files
          AFile              :TPascalFile;  //each file
begin
 for i := 0 to Length(FComments) - 1 do     //for each file
  begin
   AFile := Generator.Files[i];               //get it
   CallBack(FComments[i].FileComment, Self);  //and call procedure with it
   //call procedure for all identifiers declared in it
   ForEachIdentifier(AFile.Idents, FComments[i].IdentifierComments);
  end;
end;

{Calls the procedure for each file and identifier with their comments.
~param CallBack the procedure to call for each stored comment }
procedure TICSourceComments.ForEachIdentComment(CallBack:
                                                 TICIdentCommentsCallBackProc);

 {Calls the procedure for each identifier in the list and for all members if an
  identifier is a record-like type.
 ~param Identifiers the list of identifiers to call the procedure with
 ~param Map         the comments of the identifiers }
 procedure ForEachIdentifier(Identifiers: TIdentifierList;
                             Map: TICIdentifierComments);
 var       i             :Integer;                //counter through identifiers
           Identifier    :TIdentifier;            //each identifier
           Comments      :TIdentifierCommentValue; //its comment values
 begin
  for i := 0 to Identifiers.Count - 1 do          //for each identifier
   begin
    Identifier := Identifiers[i];                   //get it
    Comments := Map.Items[Identifier];              //get its comment values
    CallBack(Comments.Comment, Identifier, nil, Self); //call procecure for it

    if Identifier is TRecordType then               //is a record-like type?
     //call procedure for its members
     ForEachIdentifier(TRecordType(Identifier).IdentList, Comments.Members);
   end;
 end;

var       i                  :Integer;      //counter through all files
          AFile              :TPascalFile;  //each file
begin
 for i := 0 to Length(FComments) - 1 do     //for each file
  begin
   AFile := Generator.Files[i];               //get it and call
   CallBack(FComments[i].FileComment, nil, AFile, Self); //procedure for it
   //call procedure for all identifiers declared in it
   ForEachIdentifier(AFile.Idents, FComments[i].IdentifierComments);
  end;
end;










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


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

 FComments := TList.Create;             //create the list of pages
 FFiles := TStringList.Create;          //create the list of files
 FIndexComment := TICSimpleComment.Create; //create object for additional text
end;

{Frees the object and all comments. }
destructor TICUserDocComments.Destroy;
var        i                :Integer;     //counter through all pages
begin
 FIndexComment.Free;                      //free additional text
 if assigned(FComments) then              //list created?
  begin
   for i := 0 to FComments.Count - 1 do     //free all pages
    TICUserDocComment(FComments[i]).Free;
   FComments.Free;                          //and the list
  end;
 FFiles.Free;                             //free list of files

 inherited Destroy;                       //free the object
end;



{Gets the comment of the page.
~param PageIndex the index of the page to be returned
~result the requested comment of the page }
function TICUserDocComments.GetComment(PageIndex: Integer): TICUserDocComment;
begin
 Result := TICUserDocComment(FComments[PageIndex]);     //return the comment
end;



{Called to create a new page of user documentation.
~param NewPageIndex the index of the new page, must be equal ~[link PageCount]
~result the new page }
function TICUserDocComments.AddPage(NewPageIndex: Integer): TICUserDocComment;
begin
 assert(NewPageIndex = FComments.Count);

 Result := TICUserDocComment.Create;         //create object for a new page
 try
   FComments.Add(Result);                    //and add it
 except
   Result.Free;
   raise;
 end;
end;

{Sets the list of files containing the pages.
~param FileList the list of files containing the pages }
procedure TICUserDocComments.SetFileList(FileList: TStringList);
begin
 assert((FComments.Count = 0) or (FileList.Count > 0));
 assert((FileList.Count = 0) or (Integer(FileList.Objects[0]) = 0));

 FFiles.Assign(FileList);              //just use the files
end;

{Returns the (short unique) name of the file containing the page.
~param PageIndex the index of the page whose file should be returned
~result the file the page is defined in }
function TICUserDocComments.FileOfPage(PageIndex: Integer): String;
var      i                 :Integer;   //counter through the files
begin
 assert(PageIndex >= 0);
 assert(PageIndex < FComments.Count);

 i := FFiles.Count - 1;          //for each read file of the user documentation
 while (i >= 0) and              //test if it contained the current page
       (PageIndex < Integer(FFiles.Objects[i])) do
  dec(i);

 assert(i >= 0);
 Result := FFiles[i];            //return the name of the file
end;



{Calls the procedure with every stored comment/part of the documentation.
~param CallBack the procedure to be called with each comment }
procedure TICUserDocComments.ForEach(CallBack: TICCommentsCallBackProc);
var       i                 :Integer;   //counter through all pages
begin
 for i := 0 to FComments.Count - 1 do   //for each page of user documentation
  CallBack(FComments[i], Self);           //call the procedure with it
end;

{Calls the procedure with every page of user documentation.
~param CallBack the procedure to be called with each page of user
                documentation }
procedure TICUserDocComments.ForEachUserComment(CallBack:
                                                  TICUserCommentsCallBackProc);
var       i                 :Integer;   //counter through all pages
begin
 for i := 0 to FComments.Count - 1 do   //for each page of user documentation
  CallBack(TICUserDocComment(FComments[i]), Self); //call the procedure with it
end;

{Returns the number of pages/topics with additional user documentation.
~result the number of pages }
function TICUserDocComments.PageCount: Integer;
begin
 Result := FComments.Count;
end;


end.