ujaddcomments.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) 2004-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 UJADDComments;

{Contains classes to hold comments in the format of this program. The comments
 are expressed in a simple ~[linkUnit UJADDNodes DOM] - Document Object
 Model. They are later transformed to a more general ~[linkUnit UICNodes COM] -
 Comment Object Model - which is then converted to the documentation of the
 identifier or file.

 ~[link TJaddCommentData] is the central class to parse, handle and transform
 the comments, thus it is also based on the abstract class
 ~[link TCommentScanner]. Via the implemented abstract methods of that class
 the object is used by the generators to parse and transform the comments so
 they can be used in the documentation. It also contains the options to
 customize the transformation.

 ~[link TJaddComment] holds a comment in the format of this program in a simple
 DOM. It is directly used for comments of identifiers and files. Its sub-class
 ~[link TJaddUserComment] holds instead the content of a page of additional
 user documentation and the other sub-class ~[link TJaddGUIComment] holds a
 comment for documentation as a help on a GUI, a graphical user interface. They
 use the class ~[link TCommentsJaddNodeOwner] as a substitute for the
 ~[link TJaddNodeOwner default owner] of the nodes of the simple DOM of the
 comments. This owner overrides the virtual methods of the default owner to
 relay global information to the nodes when parsing and transforming them. This
 is done by calling methods or accessing properties of the comment or, mostly,
 of the list of comments holding the comment, which will ofter relay the
 request even further to the central object of the class TJaddCommentData.

 The (abstract) base class ~[link TJaddComments] manages a list of comments,
 its specialized sub-class ~[link TJaddSourceComments] does this for the
 comments of all identifiers and files. It uses the class
 ~[link TJaddIdentifierComments], which maps the identifiers to their comments
 and documentations, and in turn enlists the assistance of the class
 ~[link TIdentifierListAdapter] to map identifiers to their comments and
 documentation.

 The sub-class ~[link TJaddUserComments] manages the additional user
 documentation and contains a comment for every page in it. Similar
 ~[link TJaddGUIComments] manages the comments for the help on a GUI, but it
 contains also the data from the parsed log files via an obejct of class
 ~[link TICGUIHelpList].


 The generator object is mostly used to add messages and manage the help
 contexts and of course to access the other objects
 ~[link TMakeDoc.Extractor], ~[link TMakeDoc.Files] and
 ~[link TMakeDoc.Progress].


 The comments and documentations consist of the ~[em DOM] as defined in unit
 ~[linkUnit UJADDNodes], it is based on the (very small) class hierarchy based
 on the abstract class ~[link TJaddNode]. These nodes use their owner to get
 extended information when they are being transformed to the ~[em COM]. For
 this reason the class for the owners, ~[linkClass TJaddNodeOwner], is
 reimplemented by the class ~[linkClass TCommentsJaddNodeOwner], which will
 forward any requests for information (via virtual method calls) to the objects
 of the other classes defined in this unit. ~[linkClass TJaddCommentData], as
 the most general object, also holds several options to customize the
 transformation.
}

interface

uses Windows, Classes,
     UBaseIdents,
     UOptions, UGenerationMessages,
     UMakeDoc,
     UICDocumentDoc,
     UICNodes, UILComment, UICGUIHelpData,
     UCommentScanner,
     UComments, UJADDNodes;


          //the characters the names of the inline commands are written with
          //~todo allow to customize the names and thus these characters
const     InlineCommandNameChars = ['A'..'Z', 'a'..'z'];


type

  //a comment (of an identifier or file) in the format of this program
  TJaddComment = class;

  //a list of comments in the format of this program
  TJaddComments = class;

  //class whose objects contain the comments of all identifiers and files
  TJaddSourceComments = class;

  //class whose objects contain additional user documentation
  TJaddUserComments = class;

  //class whose objects contain the documentation of a GUI
  TJaddGUIComments = class;




   { * * *  ***  * * *  ***   TJaddCommentData   ***  * * *  ***  * * *  }



  //class of the classes to hold comments
  TJaddCommentDataClass = class of TJaddCommentData;



  {The main class scanning and holding all comments in the format of this
   program and all global information about them. This includes also options to
   customize their parsing and the transforming to the more general
   ~[linkUnit UICNodes COM] - Comment Object Model. }
  TJaddCommentData = class(TCommentScanner)
  private
    //ID of the messages of this class
    FJaddCommentMessagesID: TMessageID;

    //A list of variable texts mapped to names; similar like functions, result
    //depends on the position, where the text is requested. Can be queried by
    //~[code ~~~[[insertVariable <Name>~[]] in comments.
    FVariableTexts: TStringList;

    //handles requests of nodes in defined texts when they are transformed to
    //the COM
    FDefinedTextsComments: TJaddComments;
    //contains names of the defined texts, the objects[] are the content as
    //~[link TJaddNode]/~[link TJaddNodeCompound]
    FDefinedTexts: TStringList;

    //the comments for each identifier and file
    FSourceComments: TJaddSourceComments;
    //the additional user documentation
    FUserDocComments: TJaddUserComments;
    //the comments as a help on a GUI
    FGUIComments: TJaddGUIComments;


    //whether the formattings of the text should be kept;
    //this is not an option, the value temporarily assigned from the parameters
    //of methods ~[link PrepareComments] and ~[link TransformSourceComments]
    FKeepTextFormatting: Boolean;


    //whether currently the additional user documentation is parsed or
    //transformed
    FInUserDoc: Boolean;

    //the character used to start an inline command if followed by
    //~[link FICStartChar]
    FCommandChar: Char;
    //the character used to start an inline command if it follows
    //~[link FCommandChar]
    FICStartChar: Char;
    //the character that ends an inline command
    FICEndChar: Char;
    //whether the text should not be parsed, i.e. contains no inline commands
    FDontParseText: Boolean;


    //the list of names of the inline command, the number of the inline command
    //is encoded in the Objects
    FInlineCommandNames: TStringList;

    //whether empty lines should be treated as the end of the current paragraph
    //and the beginning of a new one, as a paragraph break
    FEmptyCommentLinesBreakParagraphs: Boolean;
    //whether links on identifiers with empty text should use a link for each
    //part of its used path instead of only a single on all;
    //whether links without text should be split for each component
    FUsePathLinks: Boolean;
    //whether the names of parameters can be used directly as names of sections
    FParameterNamesAsSections: Boolean;
    //whether the braces/brackets after inline commands are optional if no
    //parameters are expected for the inline command
    FOptionalCommandParameterBraces: Boolean;

    //whether the comments should automatically be inherited for classes or
    //members of those when no comment has been specified
    FAllowAutoInheritComment: Boolean;

    //if the automatically created auto-aliases from labels to their
    //"FocusControl"s should be used
    FGUIHelpUseAutoAliases: Boolean;
    //whether the name of the topic of a linked component should be used as
    //the alternative text for the link instead of the name of the component
    FGUIHelpUseTopicAsLinkText: Boolean;

    //Adds the default defined texts for the documentation.
    procedure AddDefinedTexts;

    //Searches the identifier or file a link points to.
    procedure FindLinkTarget(LinkTarget: String; FindType: TFindIdentifierKind;
                             FromFile: TPascalFile;
                             FromIdentifier: TIdentifier;
                             Links: TList);

  protected
    //Returns a variable text depending on the position where it is requested.
    function GetVariableTextByIndex(Index: Cardinal): String;
  public
    //Creates the object to manage all comments in the format of this program.
    constructor Create(Generator: TICDocumentDoc); override;
    //Frees the object and all comments.
    destructor Destroy; override;


    //Returns the number of available options in this class.
    class function GetOptionCount: Cardinal; override;
    //Gets a description of an option.
    class procedure GetOptionDescription(Index: Cardinal;
                                         var Desc: TOptionDescription);
                                                                      override;
    //Gets the value of an option.
    function GetOption(Index: Cardinal): TOptionValue; override;
    //Sets the value of an option.
    procedure SetOption(Index: Cardinal; Value: TOptionValue); override;


    //Resets the attributes to ready the scanner for a new generation.
    procedure ResetForNewGeneration; override;


    //Gets the characters that should be interpreted specially in the comments.
    procedure GetSpecialCharacters(var CommandChar, ICStartChar,
                                                    ICEndChar: Char);
    //Returns an inline command by its name.
    function GetInlineCommandByName(const Name: String): TJaddInlineCommand;

    //Whether the comments should be parsed, i.e. inline commands evaluated.
    function DontParseText: Boolean;
    //Returns whether the formatting of the text should be kept in the
    //documentation.
    function KeepFormat: Boolean;

    //Registers a variable text to be queried by
    //~[code ~~~[[insertVariable <Name>~[]].
    procedure RegisterVariableText(const Name: String; IndexValue: Cardinal);



    //Searches an identifier by its name and possibly its ~[em access path].
    procedure FindIdentifier(const Name: String; Kind: TFindIdentifierKind;
                             Links: TList;
                             FromFile: TPascalFile;
                             FromIdentifier: TIdentifier);

    //Returns the content of a defined text by its name.
    function GetDefinedText(const TextName: String): TJaddNode;
    //Starts defining a text by its name.
    function StartDefineText(const TextName: String): TJaddNodeCompound;
    //Ends defining a text and registers it so it can be read again.
    procedure EndDefineText(const TextName: String; Text: TJaddNodeCompound);
    //Returns the value of a variable text at the current position.
    function GetVariableText(const TextName: String;
                             var Text: String): Boolean;
    //Registers a file with additional user documentation to be included in the
    //documentation.
    function RegisterUserDocumentationFile(const FileName: String): Boolean;
    //Returns the index of the page of user documentation to link to.
    function SearchLinkPage(const PageName: String): Integer;
    //Returns the destination in the help on a GUI to link to.
    function SearchLinkGUI(const GUILink: String;
                           var CommentIndex: Integer): Integer;


    //Adds a message to the generator.
    procedure AddMessage(Msg: TJaddNodeMessages; const Text: String);
    //Adds a message at the current position.
    procedure AddPosMessage(Msg: TJaddNodeMessages; const Text: String);
    //Adds a message positioned at the specified identifier or file.
    procedure AddIdentifierMessage(Msg: TJaddNodeMessages; const Text: String;
                                   Identifier: TIdentifier;
                                   InFile: TPascalFile);



    //Reads and prepares the comments of all identifiers and files, user
    //documentation and/or help of a GUI.
    procedure PrepareComments(UserDocumentationFiles: TStrings;
                              GUIHelp: TICGUIHelpList;
                              KeepLineBreaks: Boolean;
                              UserCommentIndex: TICSimpleComment); override;

    //Transforms the comments of all identifiers and files to the COM.
    procedure TransformSourceComments(Destination: TICSourceComments;
                                      KeepLineBreaks: Boolean); override;
    //Transforms the comments as help on a GUI to the ~[linkUnit UICNodes COM].
    procedure TransformGUIHelp; override;
    //Transforms the (pages of the) additional user documentation to the COM.
    procedure TransformUserDocumentation(Destination: TICUserDocComments);
                                                                      override;






    property CommandChar: Char read FCommandChar;

    property EmptyCommentLinesBreakParagraphs: Boolean
                                        read FEmptyCommentLinesBreakParagraphs;