uicidentdocbuilder.pas

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

        begin
         //get the identifier
         Ident := Identifier.UsedIdents[i];
         //don't list functions or types, don't list fields of anonymous
         //records
         if not (Ident is TFunction) and not (Ident is TType) and
            (not assigned(Ident.MemberOf) or (Ident.MemberOf.Name <> '')) and
            not FGenerator.DoNotDocumentIdentifier(Ident) then
          List.AddIdent(Ident);              //else just add the identifier
        end;

       if not List.IsEmpty then            //list not empty?
        //show the list of used global identifiers
        AddDocumentationList(List, Identifier.MemberOf,
                             ictiFunctionUsesIdentifier, AddTo);

       List.RemoveAll(False);              //clear list
      end; //if not isfGlobals in FIdentifierSectionsFilter


     //called functions should be listed?
     if not (isfCalls in FIdentifierSectionsFilter) then
      begin
       //for each used global identifier
       for i := 0 to Identifier.UsedIdents.Count - 1 do
        begin
         Ident := Identifier.UsedIdents[i];  //get the identifier
         //only list called functions
         if (Ident is TFunction) and
            not FGenerator.DoNotDocumentIdentifier(Ident) then
          List.AddIdent(Ident);
        end;

       if not List.IsEmpty then            //list not empty?
        //show the list of the called functions
        AddDocumentationList(List, Identifier.MemberOf, ictiFunctionCalls,
                             AddTo);

      end; //if not isfCalls in FIdentifierSectionsFilter

   finally
    List.RemoveAll(False);           //remove all identifiers (don't free them)
    List.Free;                       //free the list
   end;
  end; //assigned(Identifier.UsedIdents) and not filtered
end;


{Adds the list of all identifiers using the identifier.
~param Identifier the identifier for which all identifiers using it should be
                  added
~param AddTo      the node to add the list to }
procedure TICIdentDocBuilder.AddUsedBy(Identifier: TIdentifier;
                                       AddTo: TICNCompound);
var       List              :TIdentifierList; //list of using identifiers
          i                 :Integer;         //counter through the list
          Ident             :TIdentifier;     //used global identifiers
          Kind              :TICTopicForIdentifier; //the topic for the list
begin
 if assigned(Identifier.UsedByIdents) then    //used by some identifiers?
  begin
   List := TIdentifierList.Create;              //create list for them
   try

     //for each using identifier
     for i := 0 to Identifier.UsedByIdents.Count - 1 do
      begin
       Ident := Identifier.UsedByIdents[i];       //get the identifier
       //is documented with current options?
       if not FGenerator.DoNotDocumentIdentifier(Ident) then
        List.AddIdent(Ident);                       //add the identifier
      end;
{
     if CommentIdent is TRecordType then          //is a record-like type?
      for i := List.Count - 1 downto 0 do
       if List[i] is TRecordType then                //remove all record-like
        List.Remove(i, False);                         //types using this one
}
     if not List.IsEmpty then                     //list is not empty?
      begin
       if Identifier is TFunction then              //start list of identifiers
        Kind := ictiFunctionCalledBy
       else
        Kind := ictiIdentifierUsedBy;
       //add the list
       AddDocumentationList(List, Identifier.MemberOf, Kind, AddTo);
      end;

   finally
    List.RemoveAll(False);         //remove all identifiers (don't free them)
    List.Free;                     //free the list
   end;
  end; //if assigned(CommentIdent.UsedByIdents)
end;










































{Handles the ~~deprecated, ~~todo and ~~feature sections of comments and adds
 their documentation.
~param Comment the comment to check for the special sections
~param AddTo   the node to add the documentation to }
procedure TICIdentDocBuilder.AddSpecials(Comment: TICIdentifierComment;
                                         AddTo: TICNCompound);
          //the main topic for all the special sections
var       MainNode          :TICNTopicForComment;

 {Handles the ~~deprecated, ~~todo or ~~feature sections of comments and adds
  their documentation.
 ~param Sections the list of the special sections to parse
 ~param Super    the kind of the topic for the list of sections
 ~param Single   the kind of the topic for each single special section }
 procedure AddSpecial(Sections: TICNCompound;
                      Super, Single: TICTopicForComment);
 var       SuperNode :TICNTopicForComment; //the topic for the list of sections
           i         :Integer;             //counter through all section
           Node      :TICNTopicForComment; //the topic for each single section
 begin
  SuperNode := TICNTopicForComment.CreateTopic(AddTo.Owner, Super);
  MainNode.AppendNode(SuperNode);          //create topic for list of sections

  for i := 0 to Sections.ChildCount - 1 do //for each section
   begin
    Node := TICNTopicForComment.CreateTopic(AddTo.Owner, Single);
    SuperNode.AppendNode(Node);              //create a new topic

    Node.AppendNode(Sections.Children[i].Clone(Node.Owner)); //clone content
   end;
 end;

begin
 Assert((AddTo is TICNTopicForComment) and
        (TICNTopicForComment(AddTo).Topic = ictcComment));

 //some special sections available that are not filtered?
 if (not (csfDeprecated in FCommentsSectionsFilter) and
     Comment.Deprecateds.HasChildren) or
    (not (csfToDo in FCommentsSectionsFilter) and
     Comment.ToDos.HasChildren) or
    (not (csfFeature in FCommentsSectionsFilter) and
     Comment.Features.HasChildren) then
  begin
   //create the main topic for all special sections
   MainNode := TICNTopicForComment.CreateTopic(AddTo.Owner,
                                               ictcCommentSpecials);
   AddTo.AppendNode(MainNode);                            //and add it

   if not (csfDeprecated in FCommentsSectionsFilter) and
      Comment.Deprecateds.HasChildren then
    //get and add all ~~deprecated sections
    AddSpecial(Comment.Deprecateds,
               ictcCommentDeprecateds, ictcCommentDeprecated);
   if not (csfToDo in FCommentsSectionsFilter) and
      Comment.ToDos.HasChildren then
    //get and add all ~~todo sections
    AddSpecial(Comment.ToDos, ictcCommentToDos, ictcCommentToDo);
   if not (csfFeature in FCommentsSectionsFilter) and
      Comment.Features.HasChildren then
    //get and add all ~~feature sections
    AddSpecial(Comment.Features, ictcCommentFeatures, ictcCommentFeature);
  end;
end;



{Handles the ~~see and ~~seeText sections of comments and adds their
 documentation.
~param Comment the comment to check for the sections
~param AddTo   the node to add the documentation to, either a node of the type
               ~[link TICNTopicForComment] with topic
               ~[link ictcCommentExtendedInfo], or a new node of that topic
               will be created before any information is added }
procedure TICIdentDocBuilder.AddSeeComment(Comment: TICIdentifierComment;
                                           AddTo: TICNCompound);
          //the main topic for all references
var       MainNode          :TICNTopicForComment;
          //the topic for each of the lists of references
          SuperNode         :TICNTopicForComment;
          i                 :Integer;             //counter through references
          Node              :TICNTopicForComment; //each reference
          Section           :TICNSeeSection;      //each referencing section
          //the link to the referenced identifier or file
          Link              :TICNode;
          Content           :TICNCompound;        //the additional text
begin
 //some references available that are not filtered?
 if (not (csfSee in FCommentsSectionsFilter) and
     Comment.SeeIdentifiers.HasChildren) or
    (not (csfSeeText in FCommentsSectionsFilter) and
     Comment.SeeTexts.HasChildren) then
  begin
    if not (AddTo is TICNTopicForComment) or not
       (TICNTopicForComment(AddTo).Topic = ictcCommentExtendedInfo) then
     begin
      //create and add the sub-topic for extended information about the
      //identifier or file
      MainNode := TICNTopicForComment.CreateTopic(AddTo.Owner,
                                                  ictcCommentExtendedInfo);
      AddTo.AppendNode(MainNode);
      AddTo := MainNode;                          //use it as new parent node
     end;

   //create and add the main topic for all references
   MainNode := TICNTopicForComment.CreateTopic(AddTo.Owner,
                                               ictcCommentSeeAll);
   AddTo.AppendNode(MainNode);

   //references to identifiers or files available and not filtered?
   if not (csfSee in FCommentsSectionsFilter) and
      Comment.SeeIdentifiers.HasChildren then
    begin
     //create and add the topic for the list of references
     SuperNode := TICNTopicForComment.CreateTopic(AddTo.Owner,
                                                  ictcCommentSeeSuper);
     MainNode.AppendNode(SuperNode);

     //for each reference
     for i := 0 to Comment.SeeIdentifiers.ChildCount - 1 do
      begin
       //create and add a node for the reference
       Node := TICNTopicForComment.CreateTopic(AddTo.Owner, ictcCommentSee);
       SuperNode.AppendNode(Node);

       //get the section referencing an identifier or file
       Section := TICNSeeSection(Comment.SeeIdentifiers.Children[i]);

       //referenced identifier or file available?
       if Assigned(Section.SeeIdentifier) or Assigned(Section.SeeFile) then
        //create a link to it
        Link := TICNPascalLink.CreateLink(AddTo.Owner, Section.SeeIdentifier,
                                          Section.SeeFile)
       else
        //just show its name
        Link := TICNPascalCode.CreatePascalCode(AddTo.Owner, icpcIdentifier,
                                                Section.SeeText);

       Node.AppendNode(Link);              //add the link (or name)
       if Section.HasChildren then         //some additional text available?
        begin
         //create and add a node to contain the additional text
         Content := TICNCompound.CreateCompound(AddTo.Owner);
         Node.AppendNode(Content);

         Content.AppendText(' ');            //add a separating space
         Section.CloneChildrenTo(Content);   //copy the content
        end;
      end;
    end;


   //references to external sources available and not filtered?
   if not (csfSeeText in FCommentsSectionsFilter) and
      Comment.SeeTexts.HasChildren then
    begin
     //create and add the topic for the list of references
     SuperNode := TICNTopicForComment.CreateTopic(AddTo.Owner,
                                                  ictcCommentSeeTextSuper);
     MainNode.AppendNode(SuperNode);

     //for each reference
     for i := 0 to Comment.SeeTexts.ChildCount - 1 do
      begin
       //create and add a node for the reference
       Node := TICNTopicForComment.CreateTopic(AddTo.Owner,
                                               ictcCommentSeeText);
       SuperNode.AppendNode(Node);

       //copy the content
       Node.AppendNode(Comment.SeeTexts.Children[i].Clone(Node.Owner));
      end;
    end;

  end;
end;



{Handles the ~~author and ~~version sections and the other additional
 attributes of comments and adds their documentation.
~param Comment the comment to check for the sections
~param AddTo   the node to add the documentation to, it will not be directly
               added to the node, but a new node of ~[link TICNTopicForComment]
               with topic ~[link ictcCommentExtendedInfo] will be created and
               used as the parent
~result if no nodes has been added it returns ~[code AddTo] unchanged, else
        the creates super node of type TICNTopicForComment will be re