uichtmldoc.pas

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

procedure TICSummaryVisitor.Localize(Text: TDocumentationTexts);
begin
 AddText(DocumentationTexts[Text].T);     //get and add the text
end;


{Adds some text to the summary.
~param Text the text to be added }
procedure TICSummaryVisitor.AddText(const Text: String);
begin
 FSummary := FSummary + Text;             //add the text
end;

{Stops assembling the summary. }
procedure TICSummaryVisitor.Stop;
begin
 if FFinalSummary = '' then               //not stopped, yet?
  FFinalSummary := FSummary;                //save text, stop assembling
end;


{Extracts the summary of the comment.
~param Comment the comment to extract the summary from
~result the summary line of the comment }
function TICSummaryVisitor.GetSummary(Comment: TICIdentifierComment): String;

 {Extracts the first sentence as the summary from the whole text.
 ~param Data the whole text to extract the summary from
 ~result the first sentence }
 function ExtractSummary(Data: String): String;
 var      point         :Integer;       //position of a point in comment
 begin
  Result := '';                         //no text extracted yet
  repeat
    point := Pos('.', Data);            //get position of the next point
    if point <> 0 then                    //found a point?
     begin
      Result := Result + Copy(Data, 1, point); //extract this part
      Delete(Data, 1, point);
      //a whitespace has to follow the point (could be an abbrevation)
      if (Data = '') or (Data[1] in [#0..' ']) then
       //not a single upper case letter before the point?
       if (Length(Result) <= 2) or
          not (Result[Length(Result) - 1] in ['A'..'Z']) or
          (Result[Length(Result) - 2] in ['0'..'9', 'A'..'Z',
                                          'a'..'z', #128..#255]) then
        point := 0;                               //end of the sentence reached
     end
    else
     Result := Result + Data;           //just add the whole comment
  until point = 0;                    //until sentence extracted
 end;

begin
 FSummary := '';                              //no summary so far
 FFinalSummary := '';

 if Assigned(Comment.MainDocumentation) then  //comment available?
  Comment.MainDocumentation.Visit(Self);        //extract the summary

 if FFinalSummary <> '' then                  //return the summary
  Result := FFinalSummary
 else
  Result := FSummary;
 Result := ExtractSummary(Result);            //but extract it first
end;



{Called for all text nodes in the ~[link UICNodes COM].
~param Text the text of the node }
procedure TICSummaryVisitor.Text(const Text: String);
begin
 AddText(Text);                     //just use the text
end;

{Called for all raw text nodes/raw data in the ~[link UICNodes COM].
~param Text the raw data to be inserted unchanged in the documentation }
procedure TICSummaryVisitor.RawText(const Text: String);
begin
 //ignore content
// AddText(Text);
end;

{Called for all nodes of all kinds of breaks in the ~[link UICNodes COM].
 This means line breaks or paragraph breaks.
~param BreakStyle the kind of the break }
procedure TICSummaryVisitor.Break(BreakStyle: TICBreakStyle);
begin
 Stop;                              //sentence ended
end;


{Called for nodes in the ~[link UICNodes COM] that change the style of the text
 for their contained nodes.
~param Node          the node representing a different text style
~param VisitChildren out: whether the children of the node should also be
                     visited; default is True }
procedure TICSummaryVisitor.TextStyle(Node: TICNTextStyle;
                                      var VisitChildren: Boolean);
begin
 VisitChildren := FFinalSummary = '';  //ignore if stopped
end;


{Called for nodes in the ~[link UICNodes COM] that change the font of the text
 for their contained nodes.
~param Node          the node representing a different font
~param VisitChildren out: whether the children of the node should also be
                     visited; default is True }
procedure TICSummaryVisitor.FontStyle(Node: TICNFontStyle;
                                      var VisitChildren: Boolean);
begin
 VisitChildren := FFinalSummary = '';  //ignore if stopped
end;


{Called for nodes in the ~[link UICNodes COM] that let their contained nodes
 keep their format. This means a fixed-width font should be used and line
 breaks should be preserved.
~param Node          the node causing its children to keep their format
~param VisitChildren out: whether the children of the node should also be
                     visited; default is True }
procedure TICSummaryVisitor.Preformatted(Node: TICNPreformatted;
                                         var VisitChildren: Boolean);
begin
 Stop;                                 //sentence ended
 VisitChildren := False;
end;



{Called for each link to an identifier or file.
~param Identifier the identifier to link to; nil if a link to a file
~param TheFile    the file to link to; nil if a link to an identifier }
procedure TICSummaryVisitor.LinkTo(Identifier: TIdentifier;
                                   TheFile: TPascalFile);
begin
 if assigned(Identifier) then              //add name of the target
  AddText(Identifier.Name)
 else
  AddText(TheFile.InternalFileName);
end;

{Called for each link to a file by one of its aliases (used in the uses
 clauses).
~param TheFile the file to link to
~param Alias   the used alias of the file }
procedure TICSummaryVisitor.LinkFileByAlias(TheFile: TPascalFile;
                                            const Alias: String);
begin
 AddText(TheFile.InternalFileName);        //add name of file

 Localize(dtUnitUsedByAliasPre);           //add information
 AddText(Alias);
 Localize(dtUnitUsedByAliasPost);
end;


{Called for each link whose target could not be found.
~param Node          the node with the invalid/unknown link target
~param VisitChildren out: whether the children of the node (the link text)
                     should also be visited; default is True }
procedure TICSummaryVisitor.InvalidLink(Node: TICNInvalidLink;
                                        var VisitChildren: Boolean);
begin
 VisitChildren := FFinalSummary = '';      //ignore if stopped
end;


{Called for each manual link to an identifier or file.
~param Node          the node of a link to an identifier or file
~param VisitChildren out: whether the children of the node (the link text)
                     should also be visited; default is True }
procedure TICSummaryVisitor.LinkIdentifier(Node: TICNLinkIdentifier;
                                           var VisitChildren: Boolean);
begin
 VisitChildren := False;                 //will be visited manually
 if FFinalSummary = '' then              //assembling not stopped?
  if Node.NoChildren then                  //no text of the link specified?
   AddText(Node.LinkText)                    //add the text of the target
  else
   Node.VisitChildren(Self);                 //add the text
end;

{Called for each link to a target outside of the generated documentation
 (either in the internet or in the local file system).
~param Node          the node of a link to an external target
~param VisitChildren out: whether the children of the node (the link text)
                     should also be visited; default is True }
procedure TICSummaryVisitor.LinkExtern(Node: TICNLinkExtern;
                                       var VisitChildren: Boolean);
begin
 VisitChildren := False;                    //will be visited manually
 if FFinalSummary = '' then                 //assembling not stopped?
  if Node.NoChildren then                     //no text of the link specified?
   AddText(Node.LinkText)                       //add the text of the target
  else
   Node.VisitChildren(Self);                    //add the text
end;

{Called for each link to a page of the additional user documentation.
~param Node          the node of a link to a page of user documentation
~param VisitChildren out: whether the children of the node (the link text)
                     should also be visited; default is True }
procedure TICSummaryVisitor.LinkPage(Node: TICNLinkPage;
                                     var VisitChildren: Boolean);
begin
 VisitChildren := False;                    //will be visited manually
 if FFinalSummary = '' then                 //assembling not stopped?
  if Node.NoChildren then                     //no text of the link specified?
   AddText(Node.LinkText)                       //add the text of the target
  else
   Node.VisitChildren(Self);                    //add the text
end;

{Called for each link to a help topic in the documentation as a help on a GUI.
~param Node          the node of a link to a help topic
~param VisitChildren out: whether the children of the node (the link text)
                     should also be visited; default is True }
procedure TICSummaryVisitor.LinkGUI(Node: TICNLinkGUI;
                                    var VisitChildren: Boolean);
begin
 VisitChildren := False;                    //will be visited manually
 if FFinalSummary = '' then                 //assembling not stopped?
  if Node.NoChildren then                     //no text of the link specified?
   AddText(Node.LinkText)                       //add the text of the target
  else
   Node.VisitChildren(Self);                    //add the text
end;



{Called for each node representing an image.
~param Data the node representing the options to include the image }
procedure TICSummaryVisitor.Image(Data: TICNImage);
begin
 if not Data.CharFormat then              //image in an own paragraph?
  Stop;                                     //sentence ended
end;

{Called for each node representing a diagram of classes or files.
~param Parameters the parameters to create the diagram }
procedure TICSummaryVisitor.Diagram(Parameters: TStrings);
begin
 Stop;                                    //sentence ended
end;

{Called for each node representing a short token of pascal code.
~param Code the text of the code token
~param Kind the kind of the code token }
procedure TICSummaryVisitor.PascalCode(const Code: String;
                                       Kind: TICPascalCode);
begin
 AddText(Code);                           //add the code
end;

{Called for each node representing a list. Each child node is an item in the
 list.
~param Node          the node representing a list
~param VisitChildren out: whether the children of the node (the items)
                     should also be visited; default is True }
procedure TICSummaryVisitor.List(Node: TICNList; var VisitChildren: Boolean);
begin
 Stop;                                    //sentence ended
 VisitChildren := False;
end;

{Called for each node representing a dictionary. The child nodes are used in
 pairs, the first always specifies the term to be described while the second
 contains the description.
~param Node          the node representing a dictionary
~param VisitChildren out: whether the children of the node (the terms and
                     descriptions) should also be visited; default is True }
procedure TICSummaryVisitor.Dictionary(Node: TICNDictionary;
                                       var VisitChildren: Boolean);
begin
 Stop;                                    //sentence ended
 VisitChildren := False;
end;







{Called for each node representing a topic in the documentation of identifiers
 or files as derived from its comment.
~param Node          the node representing a topic
~param VisitChildren out: whether the children of the node (the content)
                     should also be visited; default is True }
procedure TICSummaryVisitor.TopicComment(Node: TICNTopicForComment;
                                         var VisitChildren: Boolean);
begin
 Stop;                                    //sentence ended
 VisitChildren := False;
end;

{Called for each node representing a topic of the additional attributes in the
 documentation of identifiers or files as derived from its comment.
~param Node          the node representing a topic
~param VisitChildren out: whether the children of the node (the content) should
                          also be visited; default is True }
procedure TICSummaryVisitor.TopicCommentAdditional(
                                           Node: TICNTopicForCommentAdditional;
                                           var VisitChildren: Boolean);
begin
 Stop;                                    //sentence ended
 VisitChildren := False;
end;

{Called for each node containing the declaration of an identifier.
~param Node          the node containing the declaration of an identifier
~param VisitChildren out: whether the children of the node (the declaration)
                          should also be visited; default is True }
procedure TICSummaryVisitor.IdentifierDeclaration(
                                               Node: TICNIdentifierDeclaration;
                                               var VisitChildren: Boolean);
begin
 Stop;                                    //sentence ended
 VisitChildren := False;
end;

{Called for each node representing a topic in the documentation of identifiers.
~param Node          the node representing a topic
~param VisitChildren out: whether the children of the node (the content) should
                          also be visited; default is True }
procedure TICSummaryVisitor.TopicCommentIdentifier(
                                                  Node: TICNTopicForIdentifier;
                                                  var VisitChildren: Boolean);
begin
 Stop;                                    //sentence ended
 VisitChildren := False;
end;

{Called for each node representing a topic in the documentation of files.
~param Node          the node representing a topic
~param VisitChildren out: whether the children of the node (the content) should
                          also be visited; default is True }
procedure TICSummaryVisitor.TopicCommentFile(Node: TICNTopicForFile;
                                             var VisitChildren: Boolean);
begin
 Stop;                                    //sentence ended
 VisitChildren := False;