uiccommentdoc.pas

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

 Progress.SetMaximum(1 + Ord(FGenerationKind = dgkGUIHelp));

 if FGenerationKind = dgkGUIHelp then
  begin
   Progress.SetWorkText('Preparing GUI Documentation ...');
//   Progress.SetProgressText('');
//   Progress.SetProcessText('');

   //transform the documentation of the GUI to the COM
   FCommentScanner.TransformGUIHelp;

   Progress.StepProgress;
  end;


 Progress.SetWorkText('Preparing User Documentation ...');
// Progress.SetProgressText('');
// Progress.SetProcessText('');

 //transform the user documentation to the COM
 FCommentScanner.TransformUserDocumentation(FUserComments);

 Progress.StepProgress;



 //comments are now prepared, everything is in the COM
 FInCommentPreparation := False;



 Progress.SetWorkText('Building File and Identifier Documentation');
 Progress.SetProgressText('');
 Progress.SetProcessText('');
 Progress.SetMaximum(FFiles.Count + 1);

 //all final comments should be generated before generating documentation?
 if not FGenerateDocumentationOnDemand then
  begin
   //build the documentation of all identifiers and files (which is also based
   //on their comments)
   try
     FComments.ForEachIdentComment(GenerateIdentifierDocumentation);
   finally
    FCommentIdent := nil;          //after that not dealing anymore with a
    FCommentFile := nil;           //particular identifier or file
   end;
  end;

 Progress.StepProgress;
end;












































{Adds the message at the current position.
~param MsgID     the ID of the messages it should be one of
~param MsgNumber the number of the message of that ID it is
~param MsgText   the text of the message }
procedure TICCommentDoc.AddPositionMessage(MsgID: TMessageID;
                                           MsgNumber: TMessageNumber;
                                           const MsgText: String);
var       Message    :TGeneratorMessage;  //the message to add
begin
 InitMessage(Message, MsgID, MsgNumber, MsgText);  //init the message
 AssignCurrentPosition(Message.Position);          //set current position
 AddMessage(Message);                              //add the message
end;










{Resets the attributes to ready the generator for a new generation. }
procedure TICCommentDoc.ResetForNewGeneration;
begin
 inherited ResetForNewGeneration;           //reset inherited attributes

 if Assigned(FMainIndexContent) then
  begin
   FMainIndexContent.Owner.Free;              //free alternative content
   FMainIndexContent := nil;                  //for main index
  end;

 FCurrentUserDocPage := -1;                 //reset state
 FInCommentPreparation := False;
 SetCommentIdent(nil, nil);                 //no current identifier

 FCommentScanner.ResetForNewGeneration;     //reset parser of comments

 if Assigned(FGUIHelpData) then             //if was generating help on a GUI
  begin
   FGUIHelpData.Free;                         //free the data about the GUI
   FGUIHelpData := nil;
  end;
 if Assigned(FUserComments) then
  begin
   FUserComments.Free;
   FUserComments := nil;
  end;
 if Assigned(FComments) then
  begin
   FComments.Free;
   FComments := nil;
  end;

 //reset builder of documentation of identifiers and files
 FDocumentationBuilder.ResetForNewGeneration;
end;


{Lets generators initialize themselves before comments are prepared.
~param GenerationKind what kind of documentation is about to be generated }
procedure TICCommentDoc.BeforeCommentPreparation(GenerationKind:
                                                           TDocGenerationKind);
begin
 //nothing to do here
end;



{Decides how to generate the documentation.
~param Info the values used to generate the documentation
~result whether the documentation has been successfully generated and
        generation hasn't been aborted (and documentation of the kind was
        possible) }
function TICCommentDoc.GenerateDocumentationWith(const Info:
                                              TGenerationInformation): Boolean;
var      MainIndex    :TICNodeOwner; //owner of the content of the main index
begin
 //check whether the kind of documentation is supported by the generator
 case Info.Kind of
   dgkDelphiDoc: Result := True;
   dgkUserDoc:   Result := True;
   dgkGUIHelp:   Result := gcGUIHelp in Capabilities;
 else
  Result := False;
  Assert(False);
 end;

 if Result then
  begin
   //let generators initialize themselves before comments are prepared
   BeforeCommentPreparation(Info.Kind);

   //prepare all comments for the documentation
   PrepareCommentsForDocumentation(Info.UserDocumentation,
                                   Info.GUIHelpLogFiles);

   Assert(not Assigned(FMainIndexContent));
   //alternative content for the main index defined?
   if Assigned(Info.MainIndexRoot) and
      (Info.MainIndexRoot.SubTopicCount <> 0) then
    begin
     MainIndex := TICNodeOwner.Create;      //create owner for the content
     try                                    //and node to hold it
       FMainIndexContent := TICNList.CreateListSimple(MainIndex);
     except
       MainIndex.Free;
       raise;
     end;

     //transform the entries to a COM
     CreateCOMFromEntries(Info.MainIndexRoot, FMainIndexContent);
    end;


   //generate the selected kind of documentation
   case Info.Kind of
     dgkDelphiDoc: Result := DoGenerateDocumentation;
     dgkUserDoc:   Result := DoGenerateOnlyUserDocumentation;
     dgkGUIHelp:   Result := DoGenerateGUIHelp;
   else
    Result := False;
    Assert(False);
   end;
   if Result then                   //if documentation successfully generated
    PostProcessDocumentation;         //post-process it if necessary
  end;
end;














      //descriptions of the messages of the class ~[link TICCommentDoc]
const ICCommentDocMessages: array[TICCommentDocMessageKind] of
                                                          TMessageDescription =
      (
       (Text:
'The target to create a link to couldn''t be found.';
        HelpText:
'Check spelling and that the target exists and can be found from the current scope. Add the file or something similar to specify the target.';
        Seriousness: msError;
       ),
       (Text:
'The target to create a link to couldn''t be found while generating the content for the main index.';
        HelpText:
'Check spelling and that the target exists and can be found from the current scope. Add the file or something similar to specify the target.';
        Seriousness: msError;
       ),
       (Text:
'The index of the overloaded function to link to was invalid or negative.';
        HelpText:
'Check the position of the comment and whether there is a valid number after the colon ":".';
        Seriousness: msError;
       ),
       (Text:
'The target to create a link to was specified in the current record-like type (with a leading dot "."), but there is currently no record-like type.';
        HelpText:
'Check the position of the comment and if the dot "." should be removed.';
        Seriousness: msError;
       ),
       (Text:
'An index of an overloaded function to link to was specified, but the found identifier is not a function.';
        HelpText:
'Check the position of the comment and whether the identifier is supposed to be a function, either change the link target or remove the index.';
        Seriousness: msError;
       ),
       (Text:
'The index of an overloaded function to link to is too big, not enough overloaded functions found to match the index.';
        HelpText:
'Check whether the index is too big, remember for methods that they won''t be searched (and counted) for ancestor-classes, use the absolute type name if necessary to specify a method unambiguously.';
        Seriousness: msError;
       ),

       (Text:
'No identifier to inherit documentation from is available, i.e. not currently in a record-like type or it has not super class or it wasn''t parsed.';
        HelpText:
'Check the position of the inline command to inherit documentation and if it should be removed.';
        Seriousness: msError;
       ),
       (Text:
'The documentation should be inherited while not in a valid section.';
        HelpText:
'Only the main comment and comments on parameters and return value of methods can be inhertied.';
        Seriousness: msError;
       ), 
       (Text:
'The identifier to inherit documentation from is not of the same kind as the identifier to inherit it for.';
        HelpText:
'This is a problem of the parser. If you should get this error, please contact the developer of DelphiDoc.';
        Seriousness: msError;
       ),
       (Text:
'A diagram of the parsed files or classes to be inserted in the documentation was empty.';
        HelpText:
'Check that the valid data has been parsed and the files/classes, too. If some files or classes were speficified at all, other messages should already have been generated.';
        Seriousness: msError;
       ),

       (Text:
'The name of a page of user documentation was already used in another page.';
        HelpText:
'Check the name and its spelling of the pages and rename one.';
        Seriousness: msError;
       ),

       (Text:
'A log file of a GUI is not correct, at least some lines are invalid.';
        HelpText:
'Check the log file, re-create it if neccessary.';
        Seriousness: msError;
       )
      );



initialization
 //create object to manage the messages that can be generated by
 //~[link TICCommentDoc]
 ICCommentDocMessageDescriptions := TMessageDescriptions.Create(
                                        ICCommentDocMessages, 'TICCommentDoc');

 //create list for option
 OptionItemsDocumentationSectionsFilter := TStringList.Create;
 OptionItemsDocumentationSectionsFilter.AddObject('deprecated (list)',
                                                  TObject('d'));
 OptionItemsDocumentationSectionsFilter.AddObject('platform (list)',
                                                  TObject('p'));
 OptionItemsDocumentationSectionsFilter.AddObject('library (list)',
                                                  TObject('l'));
 OptionItemsDocumentationSectionsFilter.AddObject('to do (list)',
                                                  TObject('t'));
 OptionItemsDocumentationSectionsFilter.AddObject('feature (list)',
                                                  TObject('f'));
 OptionItemsDocumentationSectionsFilter.AddObject('exported (list)',
                                                  TObject('e'));
 OptionItemsDocumentationSectionsFilter.AddObject('long functions (list)',
                                                  TObject('o'));
 OptionItemsDocumentationSectionsFilter.AddObject('index (lists)',