ujaddcomments.pas

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

          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         end;
     6:  begin
          Desc.Name := 'ParamNamesAsSections';
          Desc.Category := 'Comments.Sections';
          Desc.Description := 'Whether comments of uncommented parameters should be searched in sections with their names (unless its a valid section name).';
          Desc.DataType := otBoolean;
         end;
     7:  begin
          Desc.Name := 'OptionalCommandParameterBraces';
          Desc.Category := 'Comments.Sections';
          Desc.Description := 'Whether the braces/brackets after inline commands are optional if no parameters are expected for the inline command.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         end;
     8:  begin
          Desc.Name := 'AllowAutoInheritComment';
          Desc.Category := 'Comments';
          Desc.Description := 'Whether the comments should automatically be inherited for classes or members when no comment has been specified for them.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         end;
     9:  begin
          Desc.Name := 'GUIHelpUseAutoAliases';
          Desc.Category := 'GUIHelp';
          Desc.Description := 'Whether the automatically generated aliases should be used when generating help for a GUI.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         end;
     10: begin
          Desc.Name := 'GUIHelpUseTopicAsLinkText';
          Desc.Category := 'GUIHelp';
          Desc.Description := 'Whether the name of the topic of a linked component should be used as the alternative text for the link instead of the name of the component.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         end;
     OptionCountWithoutInlineCommands..OptionCountWithoutInlineCommands +
     Ord(jicLastRealInlineCommand) - Ord(jicFirstRealInlineCommand):
         begin
          Desc.Name := 'InlineCommandName_' +
                       InlineCommandOptionNames[
                             TJaddInlineCommand(Index -
                                    OptionCountWithoutInlineCommands +
                                    Cardinal(Ord(jicFirstRealInlineCommand)))];
          Desc.Category := 'Comments.Commands.Names';
          Desc.Description := 'The comma-separated list of words to be used as this inline command.';
          Desc.Options := [ooChangesOtherOptions];

          if Index <> OptionCountWithoutInlineCommands then
           Desc.HelpOptionIndex := PreOptionCount + 
                                    OptionCountWithoutInlineCommands + 1;

          Desc.DataType := otString;
          Desc.DefaultValue.StrData := DefaultInlineCommandNames[
                 TJaddInlineCommand(Index - OptionCountWithoutInlineCommands +
                                    Cardinal(Ord(jicFirstRealInlineCommand)))];
         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 TJaddCommentData.GetOption(Index: Cardinal): TOptionValue;

 {Returns all names of the specified section separated by a comma.
 ~param Section the seciton whose names should be returned
 ~result all registered names of the sectons }
 function GetInlineCommandNames(Command: TJaddInlineCommand): String;
 var      i                    :Integer;         //counter through all names
 begin
  Result := '';
  for i := 0 to FInlineCommandNames.Count - 1 do //for each name
   //if it is a name of this inline command?
   if TJaddInlineCommand(FInlineCommandNames.Objects[i]) = Command then
    begin
     if Result <> '' then                         //not the first name
      Result := Result + ',';                       //add the separating comma
     Result := Result + FInlineCommandNames[i];   //add the name
    end;
 end;

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
  case Index - PreOptionCount of               //depending on index of option
    0:  Result.StrData := FCommandChar;          //get the value
    1:  Result.StrData := FICStartChar;
    2:  Result.StrData := FICEndChar;
    3:  Result.BoolData := FDontParseText;
    4:  Result.BoolData := FEmptyCommentLinesBreakParagraphs;
    5:  Result.BoolData := FUsePathLinks;
    6:  Result.BoolData := FParameterNamesAsSections;
    7:  Result.BoolData := FOptionalCommandParameterBraces;
    8:  Result.BoolData := FAllowAutoInheritComment;
    9:  Result.BoolData := FGUIHelpUseAutoAliases;
    10: Result.BoolData := FGUIHelpUseTopicAsLinkText;
    OptionCountWithoutInlineCommands..OptionCountWithoutInlineCommands +
    Ord(jicLastRealInlineCommand) - Ord(jicFirstRealInlineCommand):
       Result.StrData := GetInlineCommandNames(
                           TJaddInlineCommand(Index - PreOptionCount -
                                    OptionCountWithoutInlineCommands +
                                    Cardinal(Ord(jicFirstRealInlineCommand))));
  else
   Assert(Index >= GetOptionCount);          //invalid index!
   raise EInvalidOption.Create('Invalid index for option supplied!');
  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 TJaddCommentData.SetOption(Index: Cardinal; Value: TOptionValue);

 {Returns all names of the specified section separated by a comma.
 ~param Section the seciton whose names should be returned
 ~result all registered names of the sectons }
 procedure SetInlineCommandNames(Command: TJaddInlineCommand;
                                 const Names: String);
 var       i              :Integer;                 //counter through all names
           StartInd       :Integer;                 //start index of each name
           EndInd         :Integer;                 //end index of each name
           Name           :String;                  //each part of the name
 begin
  //delete all old names of the section
  for i := FInlineCommandNames.Count - 1 downto 0 do
   if TJaddInlineCommand(FInlineCommandNames.Objects[i]) = Command then
    FInlineCommandNames.Delete(i);

  StartInd := 1;
  while StartInd <= Length(Names) do                //for each name
   begin
    EndInd := SearchString(',', Names, StartInd);     //search its end
    if EndInd = 0 then
     EndInd := Length(Names) + 1;
    Name := Copy(Names, StartInd, EndInd - StartInd); //and get it
    StartInd := EndInd + 1;                           //skip to the next name

    i := FInlineCommandNames.IndexOf(Name);
    if i <> -1 then                                   //another command's name?
     FInlineCommandNames.Objects[i] := TObject(Command)    //just change it
    else
     //add name of the inline command
     FInlineCommandNames.AddObject(Name, TObject(Command));
  end;
 end;

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:  if Value.StrData <> '' then              //set the value
         FCommandChar := Value.StrData[1]
        else
         FCommandChar := #0;
    1:  if Value.StrData <> '' then
         FICStartChar := Value.StrData[1]
        else
         FICStartChar := #0;
    2:  if Value.StrData <> '' then
         FICEndChar := Value.StrData[1]
        else
         FICEndChar := #0;
    3:  FDontParseText := Value.BoolData;
    4:  FEmptyCommentLinesBreakParagraphs := Value.BoolData;
    5:  FUsePathLinks := Value.BoolData;
    6:  FParameterNamesAsSections := Value.BoolData;
    7:  FOptionalCommandParameterBraces := Value.BoolData;
    8:  FAllowAutoInheritComment := Value.BoolData;
    9:  FGUIHelpUseAutoAliases := Value.BoolData;
    10: FGUIHelpUseTopicAsLinkText := Value.BoolData;
    OptionCountWithoutInlineCommands..OptionCountWithoutInlineCommands +
    Ord(jicLastRealInlineCommand) - Ord(jicFirstRealInlineCommand):
        SetInlineCommandNames(TJaddInlineCommand(Index - PreOptionCount -
                                          OptionCountWithoutInlineCommands +
                                     Cardinal(Ord(jicFirstRealInlineCommand))),
                               Value.StrData);
  else
   Assert(Index >= GetOptionCount);     //invalid index!
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;










{Adds defined texts for the documentation. }
procedure TJaddCommentData.AddDefinedTexts;
var       Text            :TJaddNodeCompound; //compound to contain the text
begin
 Text := StartDefineText('DocClass');         //define names of classes
 try
   Text.AppendNode(TJaddNodeText.CreateText(Text.Owner, Generator.ClassName));
 finally
  EndDefineText('DocClass', Text);
 end;

 Text := StartDefineText('ExtractorClass');
 try
   Text.AppendNode(TJaddNodeText.CreateText(Text.Owner,
                                            Generator.Extractor.ClassName));
 finally
  EndDefineText('ExtractorClass', Text);
 end;

 Text := StartDefineText('CommentClass');
 try
   Text.AppendNode(TJaddNodeText.CreateText(Text.Owner, ClassName));
 finally
  EndDefineText('CommentClass', Text);
 end;

 //'EvaluatorClass' etc.
end;




{Searches a identifier or file as the target of a link.
~param LinkTarget     the identifier to generate a link to
~param FindType       what identifiers to find
~param FromFile       the file from which the search should be started
~param FromIdentifier the identifier from which the search should be started
~param Links          will be filled with the file and identifiers in the path
                      if the file or identifier can be found, the last entry
                      will be the specified file or identifier; each string
                      will be a part of Name, it hat so be concatenated with a
                      dot "." between them to regenerate the Name, but case may
                      differ, because the defined names of the identifiers will
                      be used instead of that in name; the objects to the
                      strings will be either the file or the identifier
                      represended by the string }
procedure TJaddCommentData.FindLinkTarget(LinkTarget: String;
                                          FindType: TFindIdentifierKind;
                                          FromFile: TPascalFile;
                                          FromIdentifier: TIdentifier;
                                          Links: TList);

 //Extracts the index of the overloaded function from the link target.
 function ExtractOverloadedFunctionIndex(var LinkTarget: String): Integer;
                                                                       forward;
 //Returns the overloaded function of the index of the identifier itself.
 function GetOverloadedFunction(TheIdent: TIdentifier;
                                IdentIndex: Integer): TIdentifier; forward;
 //Searches a file.
 procedure FindFile(const Name: String); forward;
 //Returns the first identifier up to the first dot ".".
 function GetFirstIdent(var IdentPath: String): String; forward;
 //Searches the identifier; it is has to be a class.
 procedure SearchClass; forward;



 {Extracts the index of the overloaded function from the link target.
 ~param LinkTarget in: the target to create a link to;
                   out: the same, but if it contained an index, it is removed
 ~result the index of the function or 0 if not specified }
 function ExtractOverloadedFunctionIndex(var LinkTarget: String): Integer;
 var      Index           :Integer;     //index in string of the link target
          FuncIndex       :String;      //the part specifying the index
 begin
  Index := Pos(':', LinkTarget);        //search separator for index
  if Index <> 0 then                    //separator (and index) specified?
   begin                                  //extract the index
    FuncIndex := Copy(LinkTarget, Index + 1, High(Length(LinkTarget)));
    Delete(LinkTarget, Index, High(Length(LinkTarget))); //and remove it

    Val(FuncIndex, Result, Index);        //read the index
    if (Index <> 0) or (Result < 0) then  //invalid index?
     begin
      AddPosMessage(jcmInvalidOverloadedFunctionIndex,
                    Format('The specified index of the overloaded function to link to is invalid: "%s"!',
                           [FuncIndex]));
      if Index <> 1 then                    //no digits at all parsed?
       Result := 0;                           //no (valid) index specified
     end;
   end
  else
   Result := 0;                         //no index specified
 end;


 {Returns the overloaded function of the index of the identifier itself.
 ~param TheIdent   the identifier whose overloaded counterpart should be
                   returned
 ~param IdentIndex the index of the overloaded identifier to return
 ~result the overloaded identifier by the index or TheIdent }
 function GetOverloadedFunction(TheIdent: TIdentifier;
                                IdentIndex: Integer): TIdentifier;
 var      List        :TIdentifierList;    //list where the identifier is in
          Index       :Integer;            //index in the list
          ToGet       :Integer;            //index of identi