uformatcommentdoc.pas

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

          ParamCount      :Integer;     //number of parameters of the function
          i               :Integer;     //general counter
          ParamTexts      :TStringList; //comment for each parameter
          //to which parameters a ~~param section applies;
          AssignText      :PBooleanArray; //array[0..ParamCount - 1] of Boolean
          Text            :String;      //the comment
          //if there are further names of parameters given in the
          OtherParams     :Boolean;     //~~param section
          ParamName       :String;      //name of the parameter of the comment
          Param           :TIdentifier; //the parameter of the comment
 begin
  Result := '';                         //no documentation so far
  ParamsCommented := False;             //no comments of parameters found
  ParamCount := Params.Count;           //get number of parameters

  //documentation of parameters not ignored?
  if not (icsParameter in FilterCommentSections) then
   begin
    if ParamCount <> 0 then               //function has some parameters?
     begin
      ParamTexts := TStringList.Create;     //create list
      try
        ParamTexts.Capacity := ParamCount;
        for i := 0 to ParamCount - 1 do     //create an empty entry for
         ParamTexts.Append('');               //each parameter

        FInheritedDocSection := idsParam;   //in comment of parameter
        try

          //get boolean array
          GetMem(AssignText, ParamCount * SizeOf(AssignText[0]));
          try
            Text := '';
            //for each ~~param section in the comment, get it
            while Comment.GetAndDeleteSection(csParameter, Text) do
             begin
              ParamsCommented := True;      //comment of some parameters found
              //clear boolean array, no parameter recognized so far
              FillChar(AssignText^, ParamCount * SizeOf(AssignText[0]), False);

              repeat                        //for each parameter of the comment
                //get its name
                OtherParams := Evaluator.ExtractParamName(Text, ParamName);
                Param := Params.GetIdentByName(ParamName); //get the parameter
                if assigned(Param) then         //parameter known?
                 begin
                  i := 0;
                  while Params[i] <> Param do   //get index of the parameter
                   inc(i);
                  if AssignText[i] or (ParamTexts[i] <> '') then
                   AddPositionMessage(FFormatCommentDocMessagesID,
                                      Ord(fcdmkParamCommentedTwice),
                        Format(DocumentationTexts[dtParameterCommentedTwice].T,
                               [ParamName]))
                  else
                   //the comment is also for this parameter
                   AssignText[i] := True;
                 end
                else
                 AddPositionMessage(FFormatCommentDocMessagesID,
                                    Ord(fcdmkUnknownParamCommented),
                      Format(DocumentationTexts[dtCommentedParameterUnknown].T,
                             [ParamName]));

              until not OtherParams;       //until all names of parameters read

              for i := 0 to ParamCount - 1 do //for each parameter
               if AssignText[i] then            //this comment is for
                begin
                 FCurrentDocParameter := TParameter(Params[i]); //set it
                 //evaluate comment and assign it for the parameter
                 ParamTexts[i] := ParseCommentText(Text);
                 if ParamTexts[i] = '' then           //make sure
                  ParamTexts[i] := ' ';                 //comment is not empty
                end;

             end; //while GetDeleteSection(csParameter, ...
          finally
           FreeMem(AssignText);             //free boolean array
          end;


          //if comments of parameters can be given by sections with their names
          if FParamNamesAsSections then
           for i := 0 to ParamCount - 1 do    //for each parameter
            if ParamTexts[i] = '' then          //that has no comment so far
             begin
              ParamName := Params[i].Name;        //get its name

              if Comment.GetAndDeleteOtherSection(ParamName, Text) then
               begin
                FCurrentDocParameter := TParameter(Params[i]); //get parameter
                ParamTexts[i] := ParseCommentText(Text);    //evaluate comment
                if ParamTexts[i] = '' then          //make sure
                 ParamTexts[i] := ' ';                //comment is not empty
                ParamsCommented := True;            //some comment found
               end;
             end; //for each parameter without a comment so far



          //if comments of parameters found or list should always be generated
          if ParamsCommented or ParameterListIfUncommented then
           begin
            i := ParamCount - 1;                //check, if each parameter
            while (i >= 0) and (ParamTexts[i] <> '') do
             dec(i);
            if i >= 0 then                      //has a comment
             AddPositionMessage(FFormatCommentDocMessagesID,
                                Ord(fcdmkParamNotCommented),
                          Format(DocumentationTexts[dtParameterNotCommented].T,
                                 [Params[i].Name]));


            //start list of parameters
            Result := Result + FCommentFormats.FParamHeader;
            for i := 0 to ParamCount - 1 do     //for each parameter
             //generate its entry in the list of parameters with its comment
             Result := Result + FCommentFormats.FParamPre +
                       IdentifierText(Params[i].Name) +
                       FCommentFormats.FParamMiddle +
                       ParamTexts[i] + FCommentFormats.FParamPost;
            //end list of parameters
            Result := Result + FCommentFormats.FParamFooter;
           end
          else
           if (not (Extractor is TSectionExtractor) or
               not TSectionExtractor(Extractor).DoNotSectionize) and
              ((ParamCount <> 1) or not (CommentIdent is TFunction) or
               not (faMessage in TFunction(CommentIdent).Attributes)) then
            AddPositionMessage(FFormatCommentDocMessagesID,
                               Ord(fcdmkParamNotCommented),
                            DocumentationTexts[dtAllParametersNotCommented].T);

        finally
         FInheritedDocSection := idsInvalid;    //not in a comment anymore
         FCurrentDocParameter := nil;           //and also not of a parameter
        end;
      finally
       ParamTexts.Free;        //free the list of the comments of the parameters
      end;
     end; //if ParamCount <> 0
   end; //if not icsParameter in FilterCommentSections



  //is a function, has a result and it may be documented?
  if IsFunction and not (icsResult in FilterCommentSections) then
   begin
    Text := '';                //get comment on the result
    if Comment.GetAndDeleteSection(csResult, Text) then
     begin
      FInheritedDocSection := idsResult;   //comment of result of a function
      try
        //generate documentation of the result and evaluate the comment
        Result := Result + FCommentFormats.FResultPre +
                           ParseCommentText(Text) +
                           FCommentFormats.FResultPost;
      finally
       FInheritedDocSection := idsInvalid;
      end;
     end
    else
     begin
      if not (Extractor is TSectionExtractor) or
         not TSectionExtractor(Extractor).DoNotSectionize then
       AddPositionMessage(FFormatCommentDocMessagesID,
                          Ord(fcdmkResultNotCommented),
                          DocumentationTexts[dtResultNotCommented].T);
      //documentation of result should nevertheless be generated?
      if ParamsCommented or (ParamCount = 0) or ResultIfUncommented then
       Result := Result + FCommentFormats.FResultPre +   //generate the empty
                          FCommentFormats.FResultPost;    //documentation
     end;
   end; //if IsFunction and not icsResult in FilterCommentSections
 end;


 {Generates the special documentation of a function.
 ~result the documentation of the current function }
 function HandleFunction: String;
 var      Text          :String;       //text of comments
          OrgMethod     :TIdentifier;  //the overridden method
          RecIdent      :TRecordType;  //the class of OrgMethod
 begin
  //generate documentation of the parameters and the result
  Result := HandleFunctionParamAndResult(TFunction(CommentIdent).Params,
                                         TFunction(CommentIdent).FuncKind =
                                         fkFunction);

  Text := '';
  //if there is at least one ~~exception section, get it
  if Comment.GetAndDeleteSection(csException, Text) then
   begin
    //start list of exception documentations
    Result := Result + FCommentFormats.FExceptionHeader;
    repeat
      //generate documentation of this exception
      Result := Result + FCommentFormats.FExceptionPre +
                GetIdentifierFileLink(Evaluator.GetInlineCommandArg(Text), '',
                                      lftClass, True) +
                FCommentFormats.FExceptionMiddle + ParseCommentText(Text) +
                FCommentFormats.FExceptionPost;
    //until all ~~exception sections have been parsed
    until not Comment.GetAndDeleteSection(csException, Text);
    //end list of exception documentations
    Result := Result + FCommentFormats.FExceptionFooter;
   end;


  //if it is a method and it "override"s another method
  if not (isfOverrides in FIdentifierSectionsFilter) and
     (faOverride in TFunction(CommentIdent).Attributes) and
     assigned(CommentIdent.MemberOf) then
   begin
    //start documentation about this fact
    Result := Result + FCommentFormats.FOverridesPre;
    //get the parent class
    RecIdent := CommentIdent.MemberOf.GetParent;
    if assigned(RecIdent) then
     //search the overridden method in the ancestors
     OrgMethod := RecIdent.FindMember(CommentIdent.Name, CommentFile, True)
    else
     OrgMethod := nil;
    //identifier found and is function/method?
    if (OrgMethod is TFunction) and not DoNotDocumentIdentifier(OrgMethod) then
     //append a link to the method
     Result := Result + GetRecordFieldNameLink(OrgMethod, True)
    else
     //append the name of the overridden method
     Result := Result + IdentifierText(CommentIdent.Name);

    //end the documentation about this fact
    Result := Result + FCommentFormats.FOverridesPost;
   end;


  //if it is a method and can be overridden
  if not (isfOverriddenBy in FIdentifierSectionsFilter) and
     ([faVirtual, faOverride, faAbstract] *
      TFunction(CommentIdent).Attributes <> []) and
     assigned(CommentIdent.MemberOf) then
   begin
    Text := '';
    //get the list of overriding methods in descendant classes
    GetOverridingMethods(TFunction(CommentIdent), CommentIdent.MemberOf,
                         Text, Text, True);
    if Text <> '' then                     //list not empty?
     //append the list to the documentation
     Result := Result + FCommentFormats.FOverriddenByPre + Text +
                        FCommentFormats.FOverriddenByPost;
   end;

  //append list of used global identifiers
  Result := Result + GetFuncGlobalsString;
 end;


 {Generates the special documentation of a function type.
 ~result the documentation of the current function type }
 function HandleFunctionType: String;
 begin
  //just use the docuemtnation of the paramters and the result
  Result := HandleFunctionParamAndResult(TFunctionType(CommentIdent).Params,
                           TFunctionType(CommentIdent).FuncKind = fkFunction);
 end;



var      Data            :String;    //documentation data
begin
 Comment := GetComment;              //get the comment
 try

   //get the main comment of the identifier
   Comment.GetAndDeleteSection(csComment, Data);
   //is a property and no comment has been given?
   if (CommentIdent is TProperty) and (TrimLeft(Data) = '') then
    Result := GetPropertyMainComment     //inherit from reading field/method
   else
    begin
     FInheritedDocSection := idsText;
     Result := ParseCommentText(Data);   //evaluate the main comment
     FInheritedDocSection := idsInvalid;
    end;

   //parse all special marking sections
   Result := GetSpecials(Comment) +
             FCommentFormats.FCommentPreIdent + Result +
             FCommentFormats.FCommentPostIdent;

   if CommentIdent is TFunction then   //if it is a function
    Data := HandleFunction               //get its special documentation
   else
    if CommentIdent is TFunctionType then //if it is a function type
     Data := HandleFunctionType            //get its special documentation
    else
     Data := '';                           //no special documentation


   if not (TIdentifierSectionsFilter(Ord(isfUsedBy) +
                                     Ord(CommentIdent is TFunction)) in
           FIdentifierSectionsFilter) then
    //get list of identifiers using this identifier
    Data := Data + GetUsedByString;


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