ucommentdoc.pas

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

   { * * *  ***  * * *  ***   TCommentDoc   ***  * * *  ***  * * *  }


    //list for the option "FilterCommentSections" of the generator
    //~[link TCommentDoc]
var OptionItemsFilterCommentSections: TStringList = nil;



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



{Creates the generator object and the different lists, assigns default values
 and registers variable text handlers. }
constructor TCommentDoc.Create;
begin
 inherited Create;                            //create the generator object

 //register messages of this class
 FCommentDocMessagesID := RegisterMessages(CommentDocMessageDescriptions);

 //create lists for tagged identifiers
 FDeprecatedList := TIdentifierFileList.Create;
 FTODOList := TIdentifierFileList.Create;
 FFeatureList := TIdentifierFileList.Create;

 FCurrentUserDocPage := -1;                   //no(t in) user documentation
 FReadUserDocCurrentFile := -1;
 FReadUserDocFiles := TStringList.Create;     //create lists for user
 FUserDocPages := TStringList.Create;         //documentation
 FUserDocPageContents := TStringList.Create;

 FHelpContextList := TStringList.Create;      //create list for help contexts
 FHelpContextList.Sorted := True;             //list is sorted (faster access)
 FHelpContextList.Duplicates := dupError;     //should not happen!

 FImageLinks := TImageLinkList.Create;        //create list for links in images

 //supports generating help on a GUI?
 if gcGUIHelp in Capabilities then
  //create reader of data about GUI to generate help about
  FGUIHelpReader := TJADDGUIHelpReader.Create(Self);
end;

{Destroys the generator object and the different lists. }
destructor TCommentDoc.Destroy;
begin
 //free reader of data about GUI to generate help about
 FGUIHelpReader.Free;

 if assigned(FImageLinks) then
  begin
   FreeImageLinks;                  //free links inside of images
   FImageLinks.Free;
  end;

 FHelpContextList.Free;           //free the lists

 FUserDocPageContents.Free;
 FUserDocPages.Free;
 FReadUserDocFiles.Free;

 FFeatureList.Free;
 FTODOList.Free;
 FDeprecatedList.Free;

 FEvaluator.Free;                 //free evaluator of comments

 //unregister messages of this class
 UnRegisterMessages(FCommentDocMessagesID);

 inherited Destroy;               //free the generator object
end;





{Returns the capabilities of this class of the generators.
~result the capabilities of this class of the generators }
class function TCommentDoc.Capabilities: TGeneratorCapabilities;
begin
 Result := inherited Capabilities + [gcExtractsComments];
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 TCommentDoc.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 4;
end;

{Gets a description of an "expert"-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 TCommentDoc.GetOptionDescription(Index: Cardinal;
                                                 var Desc: TOptionDescription);
var             PreOptionCount   :Cardinal; //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  inherited GetOptionDescription(Index, Desc)  //forward to parent's method
 else
  begin
   ClearDescription(Desc);               //clear structure
   case Index - PreOptionCount of        //depending on index of option
     0:  begin                           //set the values describing the option
          Desc.Name := 'KeepLineBreaksInComments';
          Desc.Category := 'Comments.Extract';
          Desc.Description := 'Keep the line breaks of comments (be sure not to make any line breaks in inline commands when using this option).';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         end;
     1:  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;
     2:  begin
          Desc.Name := 'ResultIfUncommented';
          Desc.Category := 'Comments';
          Desc.Description := 'Create an entry for the result of a function even if it is not commented.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := False;
         end;
     3:  begin
          Desc.Name := 'FilterCommentSections';
          Desc.Category := 'Generation.Filter';
          Desc.Description := 'What sections of comments should be completely ignored.';
          Desc.DataType := otSet;
          Desc.SetNames := OptionItemsFilterCommentSections;
          Desc.DefaultValue.SetData := 0;
         end;
   else
    assert(Index >= GetOptionCount);       //invalid index!
    raise EInvalidOption.Create('Invalid index for option supplied!');
   end;
 end;
end;

{Gets the value of an option. Call ~[link GetOptionDescription] 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
~see GetOptionCount
~see GetOptionDescription
~see SetOption }
function TCommentDoc.GetOption(Index: Cardinal): TOptionValue;
var      PreOptionCount       :Cardinal;   //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  Result := inherited GetOption(Index)         //forward to parent's method
 else
  begin
   case Index - PreOptionCount of              //depending on index of option
     0: Result.BoolData := FKeepLineBreaksInComments; //get the value
     1: Result.BoolData := FParameterListIfUncommented;
     2: Result.BoolData := FResultIfUncommented;
     3: Result.SetData := SetToOption(FFilterCommentSections,
                                       SizeOf(FFilterCommentSections));
   else
    assert(Index >= GetOptionCount);           //invalid index!
    raise EInvalidOption.Create('Invalid index for option supplied!');
   end;
  end;
end;

{Sets the value of an option. Call ~[link GetOptionDescription] 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
~see GetOptionCount
~see GetOptionDescription
~see GetOption }
procedure TCommentDoc.SetOption(Index: Cardinal; const Value: TOptionValue);
var       PreOptionCount       :Cardinal; //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  inherited SetOption(Index, Value)            //forward to parent's method
 else
  case Index - PreOptionCount of               //depending on index of option
    0:  FKeepLineBreaksInComments := Value.BoolData; //set the value
    1:  FParameterListIfUncommented := Value.BoolData;
    2:  FResultIfUncommented := Value.BoolData;
    3:  OptionToSet(Value.SetData, FFilterCommentSections,
                                   SizeOf(FFilterCommentSections));
  else
   assert(Index >= GetOptionCount);            //invalid index!
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;



{Adds all wrappers for all options of the different objects to the list.
~param List the list to add all option wrappers to }
procedure TCommentDoc.AddOptionWrappers(const List: TOptionWrapperList);
var       index      :Integer;          //counter through the list

 {Searches the next free entry in the list. }
 procedure NextFreeEntry;
 begin
  //find next free entry
  while Assigned(List[index]) and (index < Length(List)) do
   Inc(index);
  if index = Length(List) then
   raise ERangeError.Create('No free entry in list for option wrapper!');
 end;

begin
 inherited AddOptionWrappers(List);     //add inherited options

 index := 0;                            //start search at the beginning (again)

 if Assigned(FEvaluator) then           //has an evaluator?
  begin
   NextFreeEntry;                         //search a free entry
   List[index] := FEvaluator.GetOptions;  //add options of evaluator
  end;

 if Assigned(FGUIHelpReader) then       //has object to handle help on a GUI?
  begin
   NextFreeEntry;                         //search a free entry
   List[index] := FGUIHelpReader.GetOptions;  //add options of object
  end;
end;










{Returns the text (formatted) of a comment in the format of the documentation.
 Any special characters are encoded for the used format.
~param Text the text of a comment to "quote"
~result the quoted text }
function TCommentDoc.HandleRawCommentText(const Text: String): String;
begin
 Result := HandleRawText(Text);
end;


{Generates a warning for every residual section in a comment.
~param Comment the comment with the residual sections }
procedure TCommentDoc.CheckInvalidSections(Comment: TComment);
var       SectionChr :Char;              //sections separating character
          i          :TCommentSection;   //counter through all sections
          Dummy      :String;            //content of a section
begin
 if Extractor is TSectionExtractor then  //get separating character
  SectionChr := TSectionExtractor(Extractor).SectionSeparatorChar
 else
  SectionChr := DefaultSectionSeparatorChar;

 for i := Low(i) to High(i) do           //for each section
  if Comment.GetAndDeleteSection(i, Dummy) then //some comment in that section?
   //generate a warning message
   AddPositionMessage(FCommentDocMessagesID, Ord(cdmkUnknownSection),
                      'Invalid section in comment: ' +
                      SectionChr + CommentSectionOptionNames[i]);

 Dummy := Comment.OtherSectionNames;     //get unknown sections
 if Dummy <> '' then
  AddPositionMessage(FCommentDocMessagesID, Ord(cdmkUnknownSection),
                     'Invalid section(s) in comment: ' + SectionChr + Dummy);
end;



{Gets the (internal) identification (for links) of a topic of documentation of
 a GUI.
~param FileIndex  the index of the file
~param TopicIndex the index of the topic in the file;
                  -2 for the default topic or -1 for the file itself
~result the identification (internal URI) of the topic }
function TCommentDoc.GetGUIHelpURIByIndex(FileIndex,
                                          TopicIndex: Integer): String;
begin
 //get URI of the documentation of the file
 Result := 'G_' +
           TOldGUIHelpData(FGUIHelpReader.GUIHelpData[FileIndex]).BaseName;
 if TopicIndex <> -1 then               //URI of topic searched?
  if TopicIndex = -2 then                 //is default topic?
   Result := Result + '...Default'          //use it
  else
   Result := Result + '..' +                //append topic
             TOldGUIHelpData(FGUIHelpReader.GUIHelpData[FileIndex]).
                                                      CommentNames[TopicIndex];
end;



{Gets the position (for links) of a topic of documentation of a GUI.
~param Target the link target; format: [GUIFile][#Component]
~param Index  out: the index of the topic within the file
                   (-2 = default, -1 = file)
~result the file of the GUI the link points to }
function TCommentDoc.GetGUIHelpPosition(Target: String;
                                        var Index: Integer): TOldGUIHelpData;
var      i          :Integer;         //general index and counter
         FileName   :String;          //name of the referenced file
begin
 assert(assigned(FGUIHelpReader));

 Result := nil;                       //no file found so far
 //is a local link inside the same file?
 if (Target <> '') and (Target[1] = '#') then
  begin
   //currently in a file?
   if FGUIHelpReader.CurrentGUIHelpFileIndex <> -1 then
    begin
     Result := FGUIHelpReader.CurrentGUIHelpFile; //use it
     Delete(Target, 1, 1);                        //remove the reference
    end; //if FGUIHelpReader.CurrentGUIHelpFileIndex <> -1
  end //if Target[1] = '#'
 else
  begin
   FileName := Target;
   i := pos('#', FileName);             //remove the topic from the reference
   if i <> 0 then
    Delete(FileName, i, High(Length(FileName)));

   i := FGUIHelpReader.GUIHelpData.Count - 1; //search all files for it
   while (i >= 0) and
         (CompareText(TOldGUIHelpData(FGUIHelpReader.GUIHelpData[i]).BaseName,
                      FileName) <> 0) do
    dec(i);

   if i >= 0 then                       //file found?
    begin
     Result := FGUIHelpReader.GUIHelpData[i]; //get the file
     i := pos('#', Target);
     if i <> 0 then