uiccommentdoc.pas

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

{Sets the identifier of which the documentation is currently generated. These
 data is save and can be accessed to retrieve the comment on the identifier,
 create links, search other identifier and so on.
~param CommentIdent the identifier to generate documentation about; may be nil
                    to generate about the file or ending generating
                    documentation specific to identifiers/files
~param CommentFile  the file the identifier is in or the file to generate
                    documentation about; may only be nil to end the generation
                    of documentation specific to identifiers/files }
procedure TICCommentDoc.SetCommentIdent(CommentIdent: TIdentifier;
                                        CommentFile: TPascalFile);
begin
 assert(assigned(CommentFile) or not assigned(CommentIdent));
 assert(not assigned(CommentIdent) or (CommentIdent.InFile = CommentFile));

 FCommentIdent := CommentIdent;       //save these values
 FCommentFile := CommentFile;
end;




{Assigns the current position.
~param Position the structure to set the position in, has to be cleared before
                calling this method }
procedure TICCommentDoc.AssignCurrentPosition(var Position:
                                                       TDocumentationPosition);
begin
 //preparing comment and it knows the position?
 if FInCommentPreparation and Assigned(FCommentScanner.OnGetPosition) then
  //get position from the parser of comments
  FCommentScanner.OnGetPosition(Position)
 else
  if Assigned(FCommentIdent) then                 //currently at an identifier?
   Position.Identifier := FCommentIdent
  else
   if Assigned(FCommentFile) then                 //currently at a file?
    Position.TheFile := FCommentFile
   else
    if FCurrentUserDocPage <> -1 then             //in user documentation?
     begin
      Assert(FCurrentUserDocPage < FUserComments.PageCount);
      Position.UserDocPage := FUserComments.
                                        Comment[FCurrentUserDocPage].TopicName;
      Position.UserDocFile := FUserComments.FileOfPage(FCurrentUserDocPage);
     end
    else
     if Assigned(FGUIHelpData) and                //in documentation on a GUI?
        (FGUIHelpData.CurrentGUIHelpFileIndex <> -1) then
      begin                                           //get the current file
       Position.GUIPageFile := FGUIHelpData.CurrentGUIHelpFile.BaseName;
       if FGUIHelpData.CurrentGUIHelpTopic <> '' then //topic specified?
        Position.GUIPageTopic := FGUIHelpData.CurrentGUIHelpTopic;
      end
//     else
//      raise Exception.Create('Invalid/unknown position for a message!');
end;









{Called for every comment belonging to an identifier (or file). Adds it to the
 list of special identifiers, ~[link FSpecialIdentifiersList], if it is
 deprecated.
~param Comment    the comment of the identifier or file
~param Identifier the identifier the comment belongs to, nil if of a file
~param TheFile    the file the comment belongs to, nil if of an identifier
~param Sender     the list of comments containing the comment }
procedure TICCommentDoc.AddDeprecatedIdentifiers(Comment: TICIdentifierComment;
                                                 Identifier: TIdentifier;
                                                 TheFile: TPascalFile;
                                                 Sender: TICSourceComments);
begin
 if Comment.Deprecateds.HasChildren and           //is tagged deprecated and is
    not DoNotDocumentIdentifier(Identifier, TheFile) then         //documented?
  if assigned(Identifier) then                      //is an identifier?
   begin
    if not FSpecialIdentifiersList.IsIn(Identifier) then //not yet added?
     FSpecialIdentifiersList.AddIdent(Identifier);         //add it
   end
  else
   if not FSpecialIdentifiersList.IsFileIn(TheFile) then //file not yet added?
    FSpecialIdentifiersList.AddFile(TheFile);              //add it
end;

{Called for every comment belonging to an identifier (or file), adds it to
 the list of special identifiers, ~[link FSpecialIdentifiersList], if it is
 unfinished, something still has to be done for it.
~param Comment    the comment of the identifier or file
~param Identifier the identifier the comment belongs to, nil if of a file
~param TheFile    the file the comment belongs to, nil if of an identifier
~param Sender     the list of comments containing the comment }
procedure TICCommentDoc.AddUnfinishedIdentifiers(Comment: TICIdentifierComment;
                                                 Identifier: TIdentifier;
                                                 TheFile: TPascalFile;
                                                 Sender: TICSourceComments);
begin
 if Comment.ToDos.HasChildren and                 //is tagged as unfinished and
    not DoNotDocumentIdentifier(Identifier, TheFile) then      //is documented?
  if assigned(Identifier) then                      //is an identifier?
   begin
    if not FSpecialIdentifiersList.IsIn(Identifier) then //not yet added?
     FSpecialIdentifiersList.AddIdent(Identifier);         //add it
   end
  else
   if not FSpecialIdentifiersList.IsFileIn(TheFile) then //file not yet added?
    FSpecialIdentifiersList.AddFile(TheFile);              //add it
end;

{Called for every comment belonging to an identifier (or file), adds it to
 the list of special identifiers, ~[link FSpecialIdentifiersList], if it is
 missing a feature.
~param Comment    the comment of the identifier or file
~param Identifier the identifier the comment belongs to, nil if of a file
~param TheFile    the file the comment belongs to, nil if of an identifier
~param Sender     the list of comments containing the comment }
procedure TICCommentDoc.AddFeatureMissingIdentifiers(
                                                 Comment: TICIdentifierComment;
                                                 Identifier: TIdentifier;
                                                 TheFile: TPascalFile;
                                                 Sender: TICSourceComments);
begin
 if Comment.Features.HasChildren and              //tagged as missing a feature
    not DoNotDocumentIdentifier(Identifier, TheFile) then     //and documented?
  if assigned(Identifier) then                      //is an identifier?
   begin
    if not FSpecialIdentifiersList.IsIn(Identifier) then //not yet added?
     FSpecialIdentifiersList.AddIdent(Identifier);         //add it
   end
  else
   if not FSpecialIdentifiersList.IsFileIn(TheFile) then //file not yet added?
    FSpecialIdentifiersList.AddFile(TheFile);              //add it
end;

























{Transforms the entries for the main index into a COM.
~param EntryRoot   the root of the entries to be transformed
~param Destination the node to add the COM nodes to }
procedure TICCommentDoc.CreateCOMFromEntries(EntryRoot: TGUIMainIndexEntry;
                                             Destination: TICNList);

 {Transforms the single entries into the COM.
 ~param Entry the entry to be transformed
 ~param Node  the node to add the entry to }
 procedure AddEntry(Entry: TGUIMainIndexEntry; Node: TICNCompound);

  {Creates a link into the documentation as a help on a GUI.
  ~param Link the target of the link as a text
  ~param Text out: the heading of the linked topic
  ~result the generated link on a topic inside the help on a GUI }
  function CreateGUILink(const Link: String; var Text: String): TICNLinkGUI;
           //index of separator of base name and comment inside the GUI
  var      Separator    :Integer;
           Part         :String;            //each part of the link
           i            :Integer;           //counter through all logged GUIs
           Data         :TICGUIHelpData;    //the data of the GUI to link into
           List         :TICGUICommentList; //the list of comments of the GUI
           Index        :Integer;           //index of the comment to link to
  begin
   Separator := Pos('#', Link);             //search separator
   Part := Link;                            //get base name of GUI
   if Separator <> 0 then                   //link to a comment?
    Delete(Part, Separator, High(Length(Part))); //use only base name of GUI

   i := FGUIHelpData.Count - 1;             //search the GUI by its name
   while (i >= 0) and (CompareText(Part, FGUIHelpData[i].BaseName) <> 0) do
    dec(i);

   if i >= 0 then                           //GUI found?
    begin
     Data := FGUIHelpData[i];                 //get it
     if Separator <> 0 then                   //link to a comment inside it?
      begin
       Part := Link;
       Delete(Part, 1, Separator);              //extract name of the comment
       //not the default comment?
       if CompareText(Part, GUIHelpTopicSpecialPrefix + 'default') <> 0 then
        begin
         List := Data.Comments;                   //get all comments of the GUI
         Index := List.Count - 1;                 //search comment by its name
         while (Index >= 0) and (CompareText(Part, List[Index].Name) <> 0) do
          dec(Index);
         if Index < 0 then                        //not found?
          Index := -3                               //use special index
        end //if Part <> '.default'
       else
        Index := -2;
      end //if Separator <> 0
     else
      Index := -1;
    end //if i >= 0
   else
    begin
     Index := -3;                             //use special index for error
     Data := nil;                             //GUI not found
    end;

   if Index <> -3 then                        //target found?
    begin
     case Index of                              //return heading of the target
       -2: Text := Data.DefaultComment.Heading;
       -1: Text := Data.TitleOrBaseName;
     else
      Text := Data.Comments[Index].Heading;
     end;                                       //and create the link to it
     Result := TICNLinkGUI.CreateGUILink(Node.Owner, Link, i, Index);
    end
   else
    begin
     AddSimpleMessage(FICCommentDocMessagesID,  //add a warning message
                      Ord(cdmkUnknownLinkTargetInMainIndex),
                      'The target for the link in the help on a GUI couldn''t be found: ' +
                      Link);
     Result := nil;                             //target not found
    end;
  end;


  {Creates a link to a page of additional user documentation.
  ~param Link the name of the page to link to
  ~param Text out: the heading of the linked page
  ~result the generated link on a page of user documentation }
  function CreateUserDocPageLink(const Link: String;
                                 var Text: String): TICNLinkPage;
  var      i                    :Integer;     //counter through the pages
  begin
   i := FUserComments.PageCount - 1;          //search the page with the name
   while (i >= 0) and
         (CompareText(Link, FUserComments.Comment[i].TopicName) <> 0) do
    dec(i);

   if i >= 0 then                             //page found?
    begin
     Text := FUserComments.Comment[i].Title;    //return its title and
     Result := TICNLinkPage.CreatePageLink(Node.Owner, Link, i); //create link
    end
   else
    begin
     AddSimpleMessage(FICCommentDocMessagesID,  //add warning message
                      Ord(cdmkUnknownLinkTargetInMainIndex),
                      'The target for the link in the user documentation couldn''t be found: ' +
                      Link);
     Result := nil;                             //target not found
    end;
  end;


 var       AddTo         :TICNCompound;   //the node to add the text to
           DefaultText   :String;         //text to use when none given
 begin
  AddTo := nil;                           //no link created yet
  DefaultText := '';                      //no default text for the link so far
  case Entry.LinkKind of                  //depending on kind
    gmilkNone:    ;                         //nothing to be done
    gmilkGUI:     //try to create a link inside the help on a GUI
                  AddTo := CreateGUILink(Entry.LinkTarget, DefaultText);
    gmilkUserDoc: //try to create a link to a page of user documentation
                  AddTo := CreateUserDocPageLink(Entry.LinkTarget,
                                                 DefaultText);
    gmilkExtern:  begin                     //just create an external link
                   AddTo := TICNLinkExtern.CreateExternLink(Node.Owner,
                                                            Entry.LinkTarget);
                   DefaultText := Entry.LinkTarget; //show the link by default
                  end;
  end;

  if Entry.Text <> '' then                //text has been specified?
   DefaultText := Entry.Text;               //use it as text instead

  if assigned(AddTo) then                 //link created?
   Node.AppendNode(AddTo)                   //insert the link into the COM
  else
   if DefaultText <> '' then                //some text specified?
    AddTo := Node;                            //will be added instead

  if assigned(AddTo) then                 //link created or text not empty?
   AddTo.AppendText(DefaultText);           //add the text into the COM
 end;

var       i            :Integer;            //counter through contained entries
          Entry        :TGUIMainIndexEntry; //each entry
          MainNode     :TICNCompound;       //node for entry and sub-entries
          List         :TICNList;           //the list for its sub-entries
begin
 for i := 0 to EntryRoot.SubTopicCount - 1 do //for each entry
  begin
   Entry := EntryRoot.SubTopics[i];             //get it
   //create and add a node to contain the entry and its sub-entries
   MainNode := TICNCompound.CreateCompound(Destination.Owner);
   Destination.AppendNode(MainNode);
   AddEntry(Entry, MainNode);                   //show the entry

   if Entry.SubTopicCount <> 0 then             //has sub-entries?
    begin                                         //create a list for them
     List := TICNList.CreateListSimple(Destination.Owner, iciiAuto);
     MainNode.AppendNode(List);
     CreateCOMFromEntries(Entry, List);           //and add them
    end;
  end;
end;