uformatcommentdoc.pas

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

   { * * *  ***  * * *  ***   TFormatCommentDoc   ***  * * *  ***  * * *  }



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



{Creates the generator object and initializes some fields. }
constructor TFormatCommentDoc.Create;
begin
 inherited Create;                 //create the object

 //register messages of this class
 FFormatCommentDocMessagesID := RegisterMessages(
                                          FormatCommentDocMessageDescriptions);

 FNewLine := #13#10;               //set default end of line (EOL) characters
// FNewLine := General.LineDelimiter;

 FMinLongFunctionLines := 30;      //set minimum length of long functions
end;

{Frees the generator object. }
destructor TFormatCommentDoc.Destroy;
begin
 //unregister messages of this class
 UnRegisterMessages(FFormatCommentDocMessagesID);

 inherited Destroy;                      //free the object
end;





{Returns the number of available options in generators of this class.
~result the number of available "expert"-options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function TFormatCommentDoc.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 5;
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 TFormatCommentDoc.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 := 'MinLongFunctionLines';
          Desc.Category := 'Generation';
          Desc.Description := 'The minimum size (number of lines) of the body of functions to be reported as long functions.';
          Desc.DataType := otInteger;
          Desc.DefaultValue.IntData := 30;
         end;
     1:  begin
          Desc.Name := 'ParamNamesAsSections';
          Desc.Category := 'Comments.Sections';
          Desc.Description := 'If comments of uncommented parameters should be searched in sections with their names (unless its a valid section name).';
          Desc.DataType := otBoolean;
         end;
     2:  begin
          Desc.Name := 'IdentifierSectionsFilter';
          Desc.Category := 'Generation.Filter';
          Desc.Description := 'Filters some sections of the documentation of an identifier.';
          Desc.DataType := otSet;
          Desc.SetNames := OptionItemsIdentifierSectionsFilter;
         end;
     3:  begin
          Desc.Name := 'FileSectionsFilter';
          Desc.Category := 'Generation.Filter';
          Desc.Description := 'Filters some sections of the documentation of a file.';
          Desc.DataType := otSet;
          Desc.SetNames := OptionItemsFileSectionsFilter;
         end;
     4:  begin
          Desc.Name := 'DocumentationSectionsFilter';
          Desc.Category := 'Generation.Filter';
          Desc.Description := 'Filters some sections of the documentation (mostly lists).';
          Desc.DataType := otSet;
          Desc.SetNames := OptionItemsDocumentationSectionsFilter;
         end;
   else
    assert(Index >= GetOptionCount);
    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 TFormatCommentDoc.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.IntData := FMinLongFunctionLines; //get the value
     1: Result.BoolData := FParamNamesAsSections;
     2: Result.SetData := SetToOption(FIdentifierSectionsFilter,
                                      SizeOf(FIdentifierSectionsFilter));
     3: Result.SetData := SetToOption(FFileSectionsFilter,
                                      SizeOf(FFileSectionsFilter));
     4: Result.SetData := SetToOption(FDocumentationSectionsFilter,
                                      SizeOf(FDocumentationSectionsFilter));
   else
    assert(Index >= GetOptionCount);
    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 TFormatCommentDoc.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: FMinLongFunctionLines := Value.IntData;   //set the value
    1: FParamNamesAsSections := Value.BoolData;
    2: OptionToSet(Value.SetData, FIdentifierSectionsFilter,
                                  SizeOf(FIdentifierSectionsFilter));
    3: OptionToSet(Value.SetData, FFileSectionsFilter,
                                  SizeOf(FFileSectionsFilter));
    4: OptionToSet(Value.SetData, FDocumentationSectionsFilter,
                                  SizeOf(FDocumentationSectionsFilter));
  else
   assert(Index >= GetOptionCount);
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;

























{Returns the text in the format; text may already include other formats.
~param TextFormat      the format the text should be in
~param Text            the text to format
~param SkipWhitespaces out: if following white spaces should be
                            skipped/ignored
~result the formatted text }
function TFormatCommentDoc.FormatText(TextFormat: TDocumentationTextFormat;
                                      const Text: String;
                                      var SkipWhitespaces: Boolean): String;
begin
 //return if following whitespaces should be omitted
 SkipWhitespaces := FFormatSettings[TextFormat].SkipWhitespaces;
 //return the text in the requested format
 Result := FFormatSettings[TextFormat].Pre + Text +
           FFormatSettings[TextFormat].Post;
end;


{Forces a new line or paragraph to start, i.e. breaks the current line or
 paragraph.
~param InsertParagraph if a paragraph break should be returned instead of a
                       line break
~param SkipWhitespaces out: if following white spaces should be skipped/ignored
~result the line or paragraph break }
function TFormatCommentDoc.LineParagraphBreak(InsertParagraph: Boolean;
                                         var SkipWhitespaces: Boolean): String;
begin
 //return if following whitespaces should be omitted
 SkipWhitespaces := FLineParagraphBreak[InsertParagraph].SkipWhitespaces;
 //return the format
 Result := FLineParagraphBreak[InsertParagraph].Format;
end;















{Parses the ~~see and ~~seeText sections of comments and returns their
 documentation.
~param Comment the comment
~result the documentation of the sections }
function TFormatCommentDoc.ParseSeeComment(Comment: TComment): String;
var      Text             :String; //the content of each section
         SeeText          :String; //the documentation about ~~seeText sections
begin
 Result := '';                  //no documentation so far
 //for each ~~see section, get it
 while Comment.GetAndDeleteSection(csSee, Text) do
  begin
   if Result <> '' then           //some sections already parsed?
    Result := Result + HandleRawText(', '); //append a separator
   Result := Result +             //append a link to the identifier
             GetIdentifierFileLink(Evaluator.GetInlineCommandArg(Text), '',
                                   lftAuto);
   Text := ParseCommentText(Text);
   if TrimLeft(Text) <> '' then   //if some additional text specified
    Result := Result + ' ' + Text;  //append it, too
  end;


 SeeText := '';                 //no documentation of ~~seeText sections so far
 //for each ~~seeText section, get it
 while Comment.GetAndDeleteSection(csSeeText, Text) do
  begin
   if SeeText <> '' then          //some sections already parsed?
    //append a line break
    SeeText := SeeText + FLineParagraphBreak[False].Format;
   SeeText := SeeText + ParseCommentText(Text);     //append the text
  end;
 if SeeText <> '' then            //if some ~~seeText sections found
  begin
   if Result <> '' then             //also some ~~see sections found?
    //append a separating line break
    Result := Result + FLineParagraphBreak[False].Format;
   Result := Result + SeeText;      //concatenate both lists
  end;
 if Result <> '' then             //some sections found?
  if assigned(CommentIdent) then    //documentation of an identifier?
   //enclose by the appropriate format strings for identifiers
   Result := FCommentFormats.FSeePreIdent + Result +
             FCommentFormats.FSeePostIdent
  else
   //enclose by the appropriate format strings for files
   Result := FCommentFormats.FSeePreFile + Result +
             FCommentFormats.FSeePostFile;
end;

{Parses the ~~author and ~~version sections of comments and returns their
 documentation. Also parses the additional sections.
~param Comment the comment
~result the documentation of the sections }
function TFormatCommentDoc.ParseAuthorVersionAdditionals(Comment: TComment):
                                                                        String;

 {Parses the ~~author or ~~versions sections of comments and returns their
  documentation.
 ~param Section the type of section to parse
 ~result the documentation of the sections }
 function GetAttribute(Section: TCommentSection): String;
 var      Data        :String;    //the content of the section
 begin
  Result := '';                 //no documentation so far
  Data := '';
  //for each section of that type, get it
  while Comment.GetAndDeleteSection(Section, Data) do
   //add the section to the documentation