uichtmldoc.pas

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

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2003-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}


unit UICHTMLDoc;

{Contains the documentation generator ~[linkClass TICHTMLDoc] to generate
 documentation about the parsed data in the HTML format.
}

interface

uses Windows, Classes,
     General,
     UPascalConsts,
     UBaseIdents,
     UMakeDoc,
     UICNodes,
     UICBaseHTMLDoc;



type

   { * * *  ***  * * *  ***   TICHTMLFilesVisitor   ***  * * *  ***  * * *  }


  {A visitor of the ~[link UICNodes COM]-hierarchy, it is used by the generator
   ~[linkClass TICHTMLDoc] to write the COM to a file in the HTML-Format. }
  TICHTMLFilesVisitor = class(TICHTMLVisitor)
  private
  public
    //Called for each node representing a topic in the documentation of
    //identifiers or files as derived from its comment.
    procedure TopicComment(Node: TICNTopicForComment;
                           var VisitChildren: Boolean); override;

    //Called for each node containing the declaration of an identifier.
    procedure IdentifierDeclaration(Node: TICNIdentifierDeclaration;
                                    var VisitChildren: Boolean); override;
  end;






   { * * *  ***  * * *  ***   TICHTMLDoc   ***  * * *  ***  * * *  }


  //the different kinds of lists of identifiers in a file to be written
  TWriteKind = (
                wkVar,        //list of all variables
                wkThreadVar,  //list of all thread-variables
                wkConst,      //list of all constants
                wkResString,  //list of all resource-strings
                wkSimpleType, //list of all simple types (no record-likes)
                wkFunc);      //list of all functions (must be the last one)



  {This generator of documentation generates HTML (Hypertext Mark-Up Language)
   files. This is the first of all generators, explaining, why most of the
   inline commands are similar to the corresponding HTML-tags.~[br]
   A lot of HTML files (*.html) will be created in the directory for the
   documentation along with some images (*.gif) and a Cascading Style-Sheets
   file (DelphiDoc.css). The index-file is called "index.html". Just try to
   open it with a browser of your choice. }
  TICHTMLDoc = class(TICBaseHTMLDoc)
  private
  protected


    //Creates a new HTML file and writes its header.
    function CreateFile(const FileName, TitlePart, KeyWords: String;
                        HeaderContentProc: THeaderWriteProcedure
                                           = nil): TBufferStream; override;
    //Writes the footer of a HTML file and closes it.
    procedure EndFile(F: TBufferStream); override;



    //Writes a list of the functions in the current file or record-like type.
    procedure ShowFunctionList(F: TBufferStream; List: TIdentifierList);






    //Writes a short, linked list of the identifiers in the file of the
    //specified kind.
    procedure WriteVarConstFuncsList(F: TBufferStream; AFile: TPascalFile;
                                     WriteType: TWriteKind);
    //Writes a short, linked list of the record-like types in the file.
    procedure WriteRecordTypeList(F: TBufferStream; AFile: TPascalFile;
                                  Kind: TRecordKind);
    //Writes the documentation of the identifiers (of a specified kind).
    procedure WriteVarConstFuncs(F: TBufferStream;
                                 List: TIdentifierList; WriteType: TWriteKind);

    //Writes the documentation about the file.
    procedure WriteFileDocumentation(AFile: TPascalFile); override;










    //Writes the documentation of the members of the record-like type.
    procedure WriteMembers(F: TBufferStream; const Heading: String;
                           Kind: TMemberKind; FuncKind: TFunctionKind;
                           Ident: TRecordType);
    //Writes the documentation of the record-like type.
    procedure WriteClassDocumentation(Ident: TRecordType); override;

















    //Begins the documentation.
    procedure StartDocumentation;
    //Ends the documentation.
    procedure EndDocumentation;



    //Generates the help on a GUI.
    function DoGenerateGUIHelp: Boolean; override;
    //Generates only the user documentation.
    function DoGenerateOnlyUserDocumentation: Boolean; override;
    //Process parsed data; generate some documentation about it.
    function DoGenerateDocumentation: Boolean; override;
  public
    //Creates the generator object and the visitor of nodes.
    constructor Create; override;

    //Returns a description of the documentation of the generator.
    class function GetDescription: TGeneratorDescription; override;

    //Returns the capabilities of this class of generators.
    class function Capabilities: TGeneratorCapabilities; override;

        

    //Returns the unique ID of an identifier to be used in the documentation.
    function GetURIOf(Ident: TIdentifier;
                      TheFile: TPascalFile = nil): String; override;
  end;




implementation


uses SysUtils,
{$IFNDEF LINUX}
     ShellAPI,
{$ENDIF}
     UExtIdents,
     UILComment,
     UICDocumentDoc,
     UICCommentDoc,
     UDocumentationTexts;






   { * * *  ***  * * *  ***   TICSummaryVisitor   ***  * * *  ***  * * *  }

type

  {A visitor of the ~[link UICNodes COM]-hierarchy, it is used by the generator
   ~[linkClass TICHTMLDoc] to extract the summary line of functions.~[br]
   The only relevant member is the method ~[link GetSummary] to extract the
   summary from a comment. }
  TICSummaryVisitor = class(TICVisitor)
  private
    //the summary of the comment of the function
    FSummary: String;
    //the final summary of the comment of the function
    FFinalSummary: String;

    //Inserts the localized version of the text.
    procedure Localize(Text: TDocumentationTexts);

    //Adds some text to the summary.
    procedure AddText(const Text: String);
    //Stops assembling the summary.
    procedure Stop;
  public
    //Extracts the summary of the comment.
    function GetSummary(Comment: TICIdentifierComment): String;


    //Called for all text nodes in the ~[link UICNodes COM].
    procedure Text(const Text: String); override;
    //Called for all raw text nodes/raw data in the ~[link UICNodes COM].
    procedure RawText(const Text: String); override;
    //Called for all nodes of all kinds of breaks in the ~[link UICNodes COM].
    procedure Break(BreakStyle: TICBreakStyle); override;

    //Called for nodes in the ~[link UICNodes COM] that change the style of the
    //text for their contained nodes.
    procedure TextStyle(Node: TICNTextStyle; var VisitChildren: Boolean);
                                                                      override;
    //Called for nodes in the ~[link UICNodes COM] that change the font of the
    //text for their contained nodes.
    procedure FontStyle(Node: TICNFontStyle; var VisitChildren: Boolean);
                                                                      override;
    //Called for nodes in the ~[link UICNodes COM] that let their contained
    //nodes keep their format.
    procedure Preformatted(Node: TICNPreformatted; var VisitChildren: Boolean);
                                                                      override;

    //Called for each link to an identifier or file.
    procedure LinkTo(Identifier: TIdentifier; TheFile: TPascalFile); override;
    //Called for each link to a file by one of its aliases (used in the uses
    //clauses).
    procedure LinkFileByAlias(TheFile: TPascalFile;
                              const Alias: String); override;


    //Called for each link whose target could not be found.
    procedure InvalidLink(Node: TICNInvalidLink; var VisitChildren: Boolean);
                                                                      override;
    //Called for each manual link to an identifier or file.
    procedure LinkIdentifier(Node: TICNLinkIdentifier;
                             var VisitChildren: Boolean); override;
    //Called for each link to a target outside of the generated documentation.
    procedure LinkExtern(Node: TICNLinkExtern; var VisitChildren: Boolean);
                                                                      override;
    //Called for each link to a page of the additional user documentation.
    procedure LinkPage(Node: TICNLinkPage; var VisitChildren: Boolean);
                                                                      override;
    //Called for each link to a help topic in the documentation as a help on a
    //GUI.
    procedure LinkGUI(Node: TICNLinkGUI; var VisitChildren: Boolean); override;

    //Called for each node representing an image.
    procedure Image(Data: TICNImage); override;
    //Called for each node representing a diagram of classes or files.
    procedure Diagram(Parameters: TStrings); override;

    //Called for each node representing a short token of pascal code.
    procedure PascalCode(const Code: String; Kind: TICPascalCode); override;






    //Called for each node representing a list. Each child node is an item in
    //the list.
    procedure List(Node: TICNList; var VisitChildren: Boolean); override;

    //Called for each node representing a dictionary.
    procedure Dictionary(Node: TICNDictionary; var VisitChildren: Boolean);
                                                                      override;

    //Called for each node representing a topic in the documentation of
    //identifiers or files as derived from its comment.
    procedure TopicComment(Node: TICNTopicForComment;
                           var VisitChildren: Boolean); override;
    //Called for each node representing a topic of the additional attributes in
    //the documentation of identifiers or files as derived from its comment.
    procedure TopicCommentAdditional(Node: TICNTopicForCommentAdditional;
                                     var VisitChildren: Boolean); override;

    //Called for each node containing the declaration of an identifier.
    procedure IdentifierDeclaration(Node: TICNIdentifierDeclaration;
                                    var VisitChildren: Boolean); override;
    //Called for each node representing a topic in the documentation of
    //identifiers.
    procedure TopicCommentIdentifier(Node: TICNTopicForIdentifier;
                                     var VisitChildren: Boolean); override;

    //Called for each node representing a topic in the documentation of files.
    procedure TopicCommentFile(Node: TICNTopicForFile;
                               var VisitChildren: Boolean); override;
    //Called for each node representing a topic in the documentation of classes
    //(record-like types).
    procedure TopicCommentClass(Node: TICNTopicForClass;
                                var VisitChildren: Boolean); override;

    //Called for each node representing the list of parameters of a function or
    //function type as a dictionary.
    procedure ParameterList(Node: TICNParameterlist;
                            var VisitChildren: Boolean); override;
    //Called for each node representing the list of exceptions raised by a
    //function or functions of a function type as a dictionary.
    procedure ExceptionList(Node: TICNExceptionlist;
                            var VisitChildren: Boolean); override;

    //Called for each node representing a token in the list of ancestors of a
    //class or interface.
    procedure AncestorListToken(Token: TICAncestorListToken); override;
    //Called for each node representing a token in the hierarchy of classes
    //(record-like types).
    procedure ClassListToken(Token: TICClassListToken; Kind: TRecordKind);
                                                                      override;
  end;






{Inserts the localized version of the text.
~param Text the text to be written in its localized version }