uformatcommentdoc.pas

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

   Result := Result + FCommentFormats.FAdditionalAttributePre +
                      ParseCommentText(Data) +
                      FCommentFormats.FAdditionalAttributePost;
 end;

var      SectionList    :String;          //the content of the sections
         Section        :TCommentSection; //counter through sections
begin
 Result := GetAttribute(csAuthor);        //parse ~~author sections
 if Result <> '' then                     //some found? => add header
  Result := FCommentFormats.FAuthorsPre + Result +
            FCommentFormats.FAuthorsPost;

 SectionList := GetAttribute(csVersion);  //parse ~~version sections
 if SectionList <> '' then                //some found? => add header
  SectionList := FCommentFormats.FVersionsPre + SectionList +
             FCommentFormats.FVersionsPost;
 Result := Result + SectionList;          //return both lists


 //for each additional atttribute
 for Section := csFirstAdditionalAttribute to csLastAdditionalAttribute do
  begin
   SectionList := GetAttribute(Section);    //parse its sections
   if SectionList <> '' then                //some found? => add header
    SectionList := FCommentFormats.FAdditionalAttributesPre +
              Localize(TDocumentationTexts(ord(dtCommentAdditionalAttribute1) +
                                           (ord(Section) -
                                           ord(csFirstAdditionalAttribute)))) +
                FCommentFormats.FAdditionalAttributesMiddle +
                SectionList + FCommentFormats.FAdditionalAttributesPost;
   Result := Result + SectionList;          //add lists
  end;
end;

{Returns the documentation of examples in comments.
~param Comment the comment to parse the examples of
~param HeaderLinks  some links to the examples may be appended to this variable;
                    not used in this method, but in overridden method
                    ~[link UWinHelpDoc.TWinHelpDoc.ParseExampleComment]
~result the documentation of the examples
~example just a test again
~example and another one }
function TFormatCommentDoc.ParseExampleComment(Comment: TComment;
                                              var HeaderLinks: String): String;
var      Text             :String;   //the text of the example
         Number           :Integer;  //the number of the example
begin
 Result := '';            //no examples so far
 Number := 0;             //that means zero
 //for each ~~example section, get it
 while Comment.GetAndDeleteSection(csExample, Text) do
  begin
   inc(Number);                      //increment number of examples

   if assigned(CommentIdent) then    //example of an identifier
    begin
     Result := Result + FCommentFormats.FExamplePreIdent; //start new example
     if Number <> 1 then               //not first (maybe single) example?
      Result := Result + Format(' %d', [Number]);  //append number of example
     //append the example
     Result := Result + FCommentFormats.FExampleMiddleIdent +
                        ParseCommentText(Text) +
                        FCommentFormats.FExamplePostIdent;
    end
   else                              //example of a file
    begin
     Result := Result + FCommentFormats.FExamplePreFile; //start new example
     if Number <> 1 then               //not first (maybe single) example?
      Result := Result + Format(' %d', [Number]);  //append number of example
     //append the example
     Result := Result + FCommentFormats.FExampleMiddleFile +
                        ParseCommentText(Text) +
                        FCommentFormats.FExamplePostFile;
    end;
  end;

 if Number <> 0 then               //some examples found?
  //enclode the list of examples with the appropriate format strings
  Result := FCommentFormats.FExampleHeader + Result +
            FCommentFormats.FExampleFooter;
end;






{Parses the ~~deprecated, ~~todo and ~~feature sections of comments and
 returns their documentation.
~param Comment the comment
~result the documentation of the special marking sections }
function TFormatCommentDoc.GetSpecials(Comment: TComment): String;


 {Parses the ~~deprecated, ~~todo or ~~feature sections of comments and
  returns their documentation.
 ~param Section the type of section to parse
 ~param Title   the title of the documentation of the sections
 ~param List    the list to add the identifier to if section found
 ~result the documentation of the sections }
 function GetSpecial(Section: TCommentSection; Title: TDocumentationTexts;
                     List: TIdentifierFileList): String;
 var      First     :Boolean;   //if it is the first found section
          Data      :String;    //the content of the section
 begin
  Result := '';                 //no documentation so far
  Data := '';
  First := True;                //first section will be found
  //for each section of that type, get it
  while Comment.GetAndDeleteSection(Section, Data) do
   begin                          //add the section to the documentation
    Result := Result + FCommentFormats.FSpecialPre + Localize(Title) +
                       FCommentFormats.FSpecialMiddle +
                       ParseCommentText(Data) + FCommentFormats.FSpecialPost;
    if First then                 //is the first found section?
     begin
      if assigned(CommentIdent) then //add the identifier to the list
       List.AddIdent(CommentIdent)
      else
       List.AddFile(CommentFile);
      First := False;               //don't add again
     end;
   end;
 end;

var      TitleKind     :TDocumentationTexts; //kind of the title
         Special       :String; //the documentation of each type of sections
begin
 if assigned(CommentIdent) then //get title for deprecated identifiers/files
  TitleKind := dtSpecialDeprecatedIdentifier
 else
  TitleKind := dtSpecialDeprecatedFile;
 //get and parse all ~~deprecated sections
 Special := GetSpecial(csDeprecated, TitleKind, FDeprecatedList);
 if Special <> '' then          //some sections of that type found?
  //set the documentation to the documentation of that type
  Result := FCommentFormats.FSpecialListPre + Special +
            FCommentFormats.FSpecialListPost
 else
  Result := '';                   //no documentation so far

 //get and parse all ~~todo sections
 Special := GetSpecial(csTodo, dtSpecialToDo, FTODOList);
 if Special <> '' then          //some sections of that type found?
  //append to the complete documentation
  Result := Result + FCommentFormats.FSpecialListPre + Special +
                     FCommentFormats.FSpecialListPost;

 //get and parse all ~~feature sections
 Special := GetSpecial(csFeature, dtSpecialFeature, FFeatureList);
 if Special <> '' then          //some sections of that type found?
  //append to the complete documentation
  Result := Result + FCommentFormats.FSpecialListPre + Special +
                     FCommentFormats.FSpecialListPost;

 if Result <> '' then           //some documentation generated/sections found?
  //enclose the documentation with the appropriate format strings
  Result := FCommentFormats.FSpecialsPre + Result +
            FCommentFormats.FSpecialsPost;
end;









{Returns the documentation extracted from the comment of the file.
~param HeaderLinks some links to the examples may be appended to this variable;
                   simply forwarded to ~[link ParseExampleComment]
~result the documentation extracted from the comment }
function TFormatCommentDoc.GetFileComment(var HeaderLinks: String): String;
var      Comment          :TComment;     //the comment of the file
         Data             :String;       //general data of the comment
begin
 Comment := GetComment;                  //get the comment of the current file
 try
   Result := '';                         //get main comment
   Comment.GetAndDeleteSection(csComment, Result);

   FInheritedDocSection := idsText;      //parse the main comment
   Result := FCommentFormats.FCommentPreFile + ParseCommentText(Result) +
             FCommentFormats.FCommentPostFile;
   FInheritedDocSection := idsInvalid;

   //parse the see sections and the examples
   Data := ParseAuthorVersionAdditionals(Comment) +
           ParseSeeComment(Comment) +
           ParseExampleComment(Comment, HeaderLinks);

   //prepend with the special marking sections
   Result := GetSpecials(Comment) + Result;

   if Data <> '' then                    //append the see sections and examples
    Result := Result + FCommentFormats.FExtendedInfoPre + Data +
                       FCommentFormats.FExtendedInfoPost;

   CheckInvalidSections(Comment);        //check for further invalid sections
 finally
  Comment.Free;                          //free the comment
 end;






 Data := '';
 if (CommentFile.ProgramParameters <> '') and //parameters defined for program?
    not (fsfProgramParameters in FFileSectionsFilter) then
  Data := FCommentFormats.FFileCommentParameterPre +  //document them
          GetProgramParameters(CommentFile) +
          FCommentFormats.FFileCommentParameterPost;


 if not (fsfRequires in FFileSectionsFilter) then
  if CommentFile.FileType = sftPackage then   //is a package?
   if CommentFile.RequiredPackages.Count <> 0 then   //requires other packages?
    //add this and the list of required packages
    Data := Data + FCommentFormats.FFileCommentRequiredPackagesPre +
                   GetRequiredPackages(CommentFile) +
                   FCommentFormats.FFileCommentRequiredPackagesPost
   else
    Data := Data + FCommentFormats.FFileCommentRequiredPackagesNone
  else
   if CommentFile.RequiredPackages.Count <> 0 then //uses packages?
    //add this and the list of used packages
    Data := Data + FCommentFormats.FFileCommentRequiredPackagesProjectPre +
                   GetRequiredPackages(CommentFile) +
                   FCommentFormats.FFileCommentRequiredPackagesProjectPost;



 if not (fsfExporteds in FFileSectionsFilter) then
  //file exports some identifiers (library)?
  if not CommentFile.Exporteds.IsEmpty then
   //add the list of exported identifiers
   Data := Data + FCommentFormats.FFileCommentExportsPre +
                  GetExports(CommentFile) +
                  FCommentFormats.FFileCommentExportsPost
  else
   if CommentFile.FileType = sftLibrary then     //if it is a library
    //remark, that it does not export anything
    Data := Data + FCommentFormats.FFileCommentExportsNone;



 if not (fsfUsesUnits in FFileSectionsFilter) then
  if (CommentFile.UsesClauses[fpInterface] <> '') or   //uses some units?
     (CommentFile.UsesClauses[fpMain] <> '') then
   begin
    Data := Data + FCommentFormats.FFileCommentUsingHeader;

    //uses units in the interface?
    if CommentFile.UsesClauses[fpInterface] <> '' then
     //add the list of units
     Data := Data + FCommentFormats.FFileCommentUsingInterfacePre +
                    GetUnitList(CommentFile, fpInterface) +
                    FCommentFormats.FFileCommentUsingInterfacePost;

    //add that it uses/contains some files
    if CommentFile.FileType = sftPackage then          //is a package?
     Data := Data + FCommentFormats.FFileCommentUsingPackage //use "contains"
    else
     if CommentFile.FileType = sftUnit then             //if it is a unit
      //also mention, that it is the implementation part
      Data := Data + FCommentFormats.FFileCommentUsingImplementation
     else                                               //a program or library
      Data := Data + FCommentFormats.FFileCommentUsingProject; //only "uses"
    if CommentFile.UsesClauses[fpMain] = '' then          //list is empty?
     Data := Data + FCommentFormats.FFileCommentUsingNoneImplementation
    else
     //add list of used/contained units
     Data := Data + FCommentFormats.FFileCommentUsingPre +
                    GetUnitList(CommentFile, fpMain) +
                    FCommentFormats.FFileCommentUsingPost;
   end
  else                               //add that no other units are used
   Data := Data + FCommentFormats.FFileCommentUsingNone;



 if not (fsfUsedBy in FFileSectionsFilter) then
  //add list of files using this one
  Data := Data + GetUsingFiles(CommentFile);


 Result := Data + FCommentFormats.FFileCommentCommentHeader + Result;
end;


//~HeaderLinks is used to check option "ParamNamesAsSections"

{Returns the documentation with all known data of the identifier.
~HeaderLinks some links to the examples may be appended to this variable;
             simply forwarded to ~[link ParseExampleComment]
~result the documentation with all known data of the identifier }
function TFormatCommentDoc.GetIdentComment(var HeaderLinks: String): String;
var      Comment          :TComment;      //the comment of the identifier

 {Handles the parameters and the result of functions and function types.
 ~param Params     the list of parameters of the function
 ~param IsFunction if it is a function with a return type
 ~result the documentation of the parameters and maybe the result }
 function HandleFunctionParamAndResult(Params: TIdentifierList;
                                       IsFunction: Boolean): String;
          //used to access an pointer of an array as an array
 type     TBooleanArray = packed array[0..high(Integer) div SizeOf(Boolean) -
                                       1] of Boolean;
          //used to access an pointer of an array as an array
          PBooleanArray = ^TBooleanArray;

          //if at least one parameter has been commented
 var      ParamsCommented :Boolean;