uiccommentdoc.pas

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

{Writes the user documentation and returns whether there was something to be
 written.
~result whether user documentation was available and has been written }
function TICCommentDoc.CreateUserDocumentation: Boolean;
begin
 Result := UserDocumentationAvailable; //some pages of user documentation read?
 if Result then                        //user documentation available?
  begin
   SetCommentIdent(nil, nil);            //not documentation of any identifier

   try
     FCurrentUserDocPage := 0;           //start at first page
     //for each page of user documentation (even new added pages)
     while FCurrentUserDocPage < FUserComments.PageCount do
      begin
       CreateUserDocPage;                  //create its documentation
       Inc(FCurrentUserDocPage);           //and next one
      end;
   finally
    FCurrentUserDocPage := -1;           //user documentation is finished
   end;
  end;
end;

{Returns whether user documentation is available and should be written.
~result whether user documentation is available }
function TICCommentDoc.UserDocumentationAvailable: Boolean;
begin
 //some pages of user documentation read?
 Result := FUserComments.PageCount <> 0;
end;







{Clears a keyword off all special characters.
~param KeyWord the single key word to be cleared off special characters
~result the key word without commas and semicolons }
function TICCommentDoc.ClearAsKeyWords(const KeyWord: String): String;
var      i            :Integer;        //runner through the string
begin
 Result := KeyWord;
 for i := Length(Result) to 1 do       //delete all commas and semicolons
  if Result[i] in [',', ';'] then
   Delete(Result, i, 1);
end;


{Has to be overridden to generate the help on one data set of a GUI, if
 ~[link gcGUIHelp] is one of the ~[link Capabilities] of the generator.
~param Data         the data of a form to generate help about
~param AddContentTo the node to add additional content to }
procedure TICCommentDoc.GenerateGUIHelpOnData(Data: TICGUIHelpData;
                                              AddContentTo: TICNCompound);
begin
 Assert(gcGUIHelp in Capabilities);
 Assert(False);
end;


{Generates the help on the GUI with all data.
~param AddContentTo the node to which additional content for the main index
                    topic should be added }
procedure TICCommentDoc.GenerateGUIHelpDatas(AddContentTo: TICNCompound);
var       Sorted       :TStringList;        //the datas sorted by their title
          i            :Integer;            //counter through the set of datas
          Data         :TICGUIHelpData;     //each data
begin
 Sorted := TStringList.Create;              //create list to sort data
 try
   Sorted.Sorted := True;                   //list will be sorted
   for i := 0 to FGUIHelpData.Count - 1 do  //for each file
    begin
     Data := FGUIHelpData[i];                 //get it and
     //add it sorted to the list
     Sorted.AddObject(Data.TitleOrBaseName, Data);
    end;

   try
     Progress.SetWorkText('Generating GUI Help');
     Progress.SetMaximum(FGUIHelpData.Count);

     for i := 0 to Sorted.Count - 1 do      //for each documented form
      begin
       Data := TICGUIHelpData(Sorted.Objects[i]); //get the data of the form
       //set index of the data in the real list
       FGUIHelpData.CurrentGUIHelpFileIndex := FGUIHelpData.IndexOf(Data);

       Progress.SetProgressText(Format('Writing %d of %d',
                                       [i + 1, Sorted.Count]));
       Progress.SetProcessText(Data.TitleOrBaseName);

       //write the help about its GUI
       GenerateGUIHelpOnData(Data, AddContentTo);

       Progress.StepProgress;
      end;
   finally
    FGUIHelpData.CurrentGUIHelpFileIndex := -1; //not in GUI help data anymore
   end;
 finally
  Sorted.Free;                             //free list to sort data
 end;
end;

























{Generate the help on a GUI. Only valid and only has to be implemented if
 ~[link gcGUIHelp] is one of the ~[link Capabilities] of the generator.
~result whether the documentation has been successfully generated and
        generation hasn't been aborted }
function TICCommentDoc.DoGenerateGUIHelp: Boolean;
begin
 Result := False;                    //not implemented in this class
 Assert(False);                      //therefore should never be called
end;





{Returns the final comment of a file, has to be
 ~[link ReleaseFinalComment released] after that.
~param OfFile the file whose final documentation should be returned
~result the documentation of the file }
function TICCommentDoc.GetFinalFileComment(OfFile: TPascalFile):
                                                              TICSimpleComment;
var      Comment      :TICIdentifierComment;  //the comment of the file
begin
 if FGenerateDocumentationOnDemand then  //comment has to be created on demand?
  begin
   Result := TICSimpleComment.Create;      //create the (empty) documentation
   try
     Comment := Comments.FileComment[OfFile];   //get the comment of the file
     //generate the documentation
     FDocumentationBuilder.GetFileComment(OfFile, Comment, Result);
     Result.HelpContext := Comment.HelpContext; //also use the help context
   except
    Result.Free;
    raise;
   end;
  end
 else
  Result := Comments.FinalFileComment[OfFile];  //just return its final comment
end;

{Returns the final comment of an identifier, has to be
 ~[link ReleaseFinalComment released] after that.
~param Identifier the identifier whose final documentation should be returned
~result the documentation of the identifier }
function TICCommentDoc.GetFinalIdentifierComment(Identifier: TIdentifier):
                                                              TICSimpleComment;
var      Comment      :TICIdentifierComment;  //the comment of the file
begin
 if FGenerateDocumentationOnDemand then  //comment has to be created on demand?
  begin
   Result := TICSimpleComment.Create;      //create the (empty) documentation
   try
     Comment := Comments.Comment[Identifier];   //get comment of the identifier
     if Identifier is TRecordType then          //generate the documentation
      FDocumentationBuilder.GetClassComment(TRecordType(Identifier), Comment,
                                            Result)
     else
      FDocumentationBuilder.GetIdentifierComment(Identifier, Comment, Result);
     Result.HelpContext := Comment.HelpContext; //also use the help context
   except
    Result.Free;
    raise;
   end;
  end
 else
  Result := Comments.FinalComment[Identifier];  //just return its final comment
end;

{Releases a comment after being requested via ~[link GetFinalFileComment]
 or ~[link GetFinalIdentifierComment].
~param Comment the comment to be released }
procedure TICCommentDoc.ReleaseFinalComment(Comment: TICSimpleComment);
begin
 if FGenerateDocumentationOnDemand then  //comment was created on demand?
  Comment.Free;                            //free now
end;



{Generates the internal representation of the documentation for the identifier
 or file. It will be saved in the appropriate property
 (~[link TICSourceComments.FinalComment FinalComment] or
  ~[link TICSourceComments.FinalFileComment FinalFileComment]) of the
 ~[link TICSourceComments Sender].
~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 }
procedure TICCommentDoc.GenerateIdentifierDocumentation(
                                                 Comment: TICIdentifierComment;
                                                 Identifier: TIdentifier;
                                                 TheFile: TPascalFile;
                                                 Sender: TICSourceComments);
          //the generated documentation as a comment
var       Target       :TICSimpleComment;
begin
 Assert(Assigned(Identifier) <> Assigned(TheFile));

 FCommentIdent := Identifier;            //set the current identifier or file
 FCommentFile := TheFile;

 Target := TICSimpleComment.Create;      //create the (empty) documentation
 try
   //generate the documentation depending on the kind of identifier/file
   if Assigned(Identifier) then
    begin
     if Identifier is TRecordType then
      FDocumentationBuilder.GetClassComment(TRecordType(Identifier), Comment,
                                            Target)
     else
      FDocumentationBuilder.GetIdentifierComment(Identifier, Comment, Target);
     Sender.FinalComment[Identifier] := Target;   //save the documentation
    end
   else
    begin
     if FFiles[0] <> TheFile then          //not the first file in the list?
      Progress.StepProgress;                 //previous file has been handled

     //show progressing to the current file
     Progress.SetProgressText(Format('File %d of %d',
                                     [FFiles.IndexOf(TheFile) + 1,
                                      FFiles.Count]));
     Progress.SetProcessText(TheFile.InternalFileName);

     //generate documentation and save it
     FDocumentationBuilder.GetFileComment(TheFile, Comment, Target);
     Sender.FinalFileComment[TheFile] := Target;
    end;
 except
   Target.Free;
   raise;
 end;
 Target.HelpContext := Comment.HelpContext; //also use the help context
end;



{Reads and transforms the comments of all identifiers and files and builds
 their documentation in the internal representation.
~param UserDocumentationFiles the files with (additional) user documentation
~param GUIHelpLogFiles        if FGenerationKind = dgkGUIHelp the list of log
                              files of a GUI to generate the documentation
                              about as a help }
procedure TICCommentDoc.PrepareCommentsForDocumentation(UserDocumentationFiles,
                                                    GUIHelpLogFiles: TStrings);
begin
 FInCommentPreparation := True;

 Assert(not Assigned(FUserComments));
 if Assigned(FUserComments) then        //some comments had already been read?
  begin
   FUserComments.Free;                    //free the old ones
   FUserComments := nil;
  end;
 FUserComments := TICUserDocComments.Create(Self); //create a new, empty one


 Assert(not Assigned(FComments));
 if Assigned(FComments) then            //some comments had already been read?
  begin
   FComments.Free;                        //free the old ones
   FComments := nil;
  end;
 FComments := TICSourceComments.Create(Self); //create object for all comments


 if Assigned(FGUIHelpData) then         //data of GUI had already been parsed?
  begin
   FGUIHelpData.Free;                     //free the old one
   FGUIHelpData := nil;
  end;
 if FGenerationKind = dgkGUIHelp then   //help on a GUI should be generated?
  begin
   FGUIHelpData := TICGUIHelpList.Create; //create the list and parse the data
   FGUIHelpData.ParseAllLogFiles(GUIHelpLogFiles, Self,
                                 FICCommentDocMessagesID,
                                 Ord(cdmkGUILogFileInvalid));
  end;



 //now read, parse and prepare all comments and other data
 FCommentScanner.PrepareComments(UserDocumentationFiles,
                                 FGUIHelpData,
                                 FKeepLineBreaksInComments,
                                 FUserComments.IndexComment);



 Progress.SetWorkText('Building File and Identifier Documentation');
 Progress.SetProgressText('');
 Progress.SetProcessText('');
 Progress.SetMaximum(1);
 Progress.SetProgressText('Transforming all Comments to general Nodes');

 //transform the (JADD-style-)comments of all identifiers and files to the
 //general representation
 FCommentScanner.TransformSourceComments(Comments, FKeepLineBreaksInComments);

 Progress.StepProgress;