ujaddnodes.pas

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

                       jcmImageLinks,
                       //documentation can't be inherited at this position
                       jcmInheritDocumentationNotPossible,
                       //there are no parameters available at this position to
                       //be documented
                       jcmNoParametersToDocument,

                       //the index of the overloaded function to link to is
                       //invalid, i.e. either not a number or negative
                       jcmInvalidOverloadedFunctionIndex,
                       //an index of the overloaded function to link to was
                       //specified but the found identifier is not a function
                       jcmIdentifierNotAFunctionButLinkWithIndex,
                       //an index of the overloaded function to link to was
                       //specified but the index is bigger than the number of
                       //overloaded functions
                       jcmNotEnoughOverloadedFunctionsForIndex,
                       //the syntax to link inside the current record-like
                       //identifier has been used (by using a leading dot "."),
                       //but the position is not inside a record-like type
                       jcmInRecordLinkOutsideRecord,


                       //some documented topics for a GUI have not been used
                       jcmUnusedTopics,

                       //a file with help on a GUI can't be read
                       jcmCantReadFile,
                       //a file with help on a GUI has already be read
                       jcmDoubleFiles,
                       //the target of a manual link in the image of the GUI
                       //was not found, it is assumed it is an external link
                       jcmInvalidManualExternalLink,
                       //a component on the GUI was not documented
                       jcmNotDocumented,
                       //some components on the GUI don't have their help
                       //context set
                       jcmNoHelpContext,

                       //invalid alias specified
                       jcmInvalidAliasNames,
                       //recursive aliases specified
                       jcmRecursiveAliasNames,
                       //invalid manual link specified
                       jcmInvalidManualLink,
                       //already specified documentation has been
                       //replaced/overridden
                       jcmDocumentationReplaced,
                       //unknown name of special documentation specified
                       jcmUnknownSpecialDocumentation,
                       //no or an invalid name of a topic/of a component
                       //specified for a topic
                       jcmInvalidTopicName,
                       //text outside of sections in included files
                       jcmTextOutsideSection,
                       //a file of documentation is invalid, i.e. none
                       //specified or not found
                       jcmDocumentationFileInvalid,

                       //no section/topic heading for the documentation of a
                       //component of a GUI specified
                       jcmNoTopicHeading
                     );




  //the abstract base class of all nodes of this simple DOM
  TJaddNode = class;
  //the (abstract) base class of all nodes in this simple DOM that contain
  //other nodes
  TJaddNodeCompound = class;
  //the class of nodes that represent inline commands
  TJaddNodeInlineCommand = class;
  //the class of nodes that represent sections (as root of DOMs)
  TJaddNodeSection = class;




   { * * *  ***  * * *  ***   TJaddNodeOwner   ***  * * *  ***  * * *  }

  //the hint on how to find an identifier to link to
  TFindIdentifierKind = (
                         //no hint at all, find any matching identifier or file
                         fikAll,
                         //find only record-like types
                         fikClass,
                         //find only files
                         fikFile,
                         //find only classes descending from ~[code Exception]
                         fikException,
                         //find any matching identifier or file
                         fikSeeAlso
                        );

  {The base class for classes owning nodes in this simple DOM. It is
   responsible for freeing the owned nodes eventually. This is made to ease the
   pain of creating and adding nodes without writing long error handling code
   every time.

   This class is not abstract, but it itself is never instantiated. It contains
   several virtual methods that are called by the nodes to get global
   information when evaluating inline commands and transforming to the general
   ~[linkUnit UICNodes COM] - Comment Object Model. These are implemented in
   the used sub-class, ~[linkClass UJADDComments.TCommentsJaddNodeOwner]. }
  TJaddNodeOwner = class
  private
    //the list of owned nodes
    FList: TList;
    //whether the text should be inserted pre-formatted (as-is) in the
    //documentation; this is a counter to allow nesting of the appropriate
    //inline commands; any value other than 0 is interpreted in that way, that
    //the text should be used pre-formatted
    FPreformattedNum: Integer;
  public
    //Creates the owner of the nodes and the list for the owned nodes.
    constructor Create;
    //Frees this object and all owned nodes.
    destructor Destroy; override;

    //Adds a node so it is owned (and eventually freed) by this object.
    procedure AddNode(Node: TJaddNode);


    //Checks whether the string is valid to be used as name for a defined text.
    function CheckNameOfDefinedText(const TextName: String): Boolean;

    //Returns whether an empty line within the comment is interpreted as the
    //end of the current paragraph (a paragraph-break).
    function EmptyCommentLinesBreakParagraphs: Boolean; virtual;
    //Returns 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.
    function UsePathLinks: Boolean; virtual;

    //Returns the content of a defined text by its name.
    function GetDefinedText(const TextName: String): TJaddNode; virtual;
    //Starts defining a text by its name.
    function StartDefineText(const TextName: String): TJaddNodeCompound;
                                                                       virtual;
    //Ends defining a text and registers it so it can be read again.
    procedure EndDefineText(const TextName: String;
                            Text: TJaddNodeCompound); virtual;
    //Returns the value of a variable text at the current position.
    function GetVariableText(const TextName: String;
                             var Text: String): Boolean; virtual;
    //Reads the content of a file to be included in the documentation unquoted.
    function ReadRawFile(const FileName: String;
                         var Content: String): Boolean; virtual;
    //Registers a file with additional user documentation to be included in the
    //documentation.
    function RegisterUserDocumentationFile(const FileName: String): Boolean;
                                                                       virtual;
    //Sets the help context for the current comment.
    procedure SetHelpContext(HelpContext: THelpContext); virtual;
    //Tries to inherit documentation for the current position.
    function InheritDocumentation(ToNode: TICNCompound): Boolean; virtual;
    //Changes whether text should be inserted pre-formatted (as-is) in the
    //documentation.
    procedure ChangePreformattedState(Delta: Integer); virtual;
    //Returns whether text should be inserted pre-formatted (as-is) in the
    //documentation.
    function GetPreformattedState: Boolean; virtual;
    //Returns the index of the parameter with the specified name or -1.
    function FindParameterIndex(const ParameterName: String): Integer; virtual;
    //Sets the index of the parameter whose documentation is currently
    //transformed.
    procedure SetCurrentParameterIndex(ParamIndex: Integer); virtual;
    //Searches an identifier by its name (possibly with its ~[em path]).
    procedure FindIdentifier(const Name: String; Kind: TFindIdentifierKind;
                             Links: TList); virtual;
    //Returns the index of the page of user documentation to link to.
    function SearchLinkPage(const PageName: String): Integer; virtual;
    //Returns the destination in the help on a GUI to link to.
    function SearchLinkGUI(const GUILink: String;
                           var CommentIndex: Integer): Integer; virtual;

    //Returns the value of an option of one of the objects used to generate the
    //documentation if it exists.
    function GetOptionValue(const OptionName: String;
                            var OptionValue: String): Boolean; virtual;


    //Returns the absolute path, if a relative path is specified it is
    //interpreted relative to the current path.
    function GetFullPath(const FileName: String): String; virtual;

    //Adds a message to the generator.
    procedure AddMessage(Msg: TJaddNodeMessages; const Text: String); virtual;
    //Adds a formatted message to the generator.
    procedure AddMessageFmt(Msg: TJaddNodeMessages; const Fmt: String;
                            const Args: array of const);
  end;





   { * * *  ***  * * *  ***   TJaddNode   ***  * * *  ***  * * *  }

  {The abstract base class of the nodes in the simple
   ~[linkUnit UJADDNodes DOM] - Document Object Model - used temporarily to
   parse comments in the style of this program, evaluate inline commands and
   tranform it to the more general ~[linkUnit UICNodes COM] - Comment Object
   Model. }
  TJaddNode = class
  private
    //the owner of the node, it is responsible for freeing it and provides
    //methods to access further information while parsing and transforming the
    //DOM
    FOwner: TJaddNodeOwner;
    //the node that contains this node, i.e. this node can be found in that
    //node's ~[link TJaddNodeCompound.Children Children] property;
    //only changed/set/written to in ~[link TJaddNodeCompound.AppendNode]!!
    FParent: TJaddNodeCompound;


    //Uniques all whitespaces to a single space ' '. Empty lines are
    //transformed into a paragraph break.
    procedure ParagraphizeText(Text: String; ToNode: TICNCompound;
                               IgnoreWhiteSpace: Boolean);

  protected
    //Optimizes text by compressing white spaces to a single space ' '.
    procedure OptimizeText(Text: String; ToNode: TICNCompound;
                           IgnoreWhiteSpace: Boolean = False);

    {Transforms the node to the more general ~[linkUnit UICNodes COM].
    ~param ToNode      the node to which the transformed node should be added
    ~param DestComment the comment the tranformed node will be part of }
    procedure TransformToIC(ToNode: TICNCompound;
                            DestComment: TICDocComment); virtual; abstract;
    //Checks whether this node is inside a link.
    function InALink: Boolean;
  public
    //Creates the object and registers itself to its owner.
    constructor Create(Owner: TJaddNodeOwner);

    {Copies the node and all its children to the specified node.
    ~param Compound the node to which a copy of this node should be added }
    procedure CopyTo(Compound: TJaddNodeCompound); virtual; abstract;

    property Owner: TJaddNodeOwner read FOwner;
    property Parent: TJaddNodeCompound read FParent;
  end;


   { * * *  ***  * * *  ***   TJaddNodeText   ***  * * *  ***  * * *  }

  {The class for simple texts in the simple ~[linkUnit UJADDNodes DOM]. All it
   contains is the text. The text may be formatted by the parent nodes. }
  TJaddNodeText = class(TJaddNode)
  private
    //the text represented by this node
    FText: String;
  protected
    //Transforms the node to the more general ~[linkUnit UICNodes COM].
    procedure TransformToIC(ToNode: TICNCompound;
                            DestComment: TICDocComment); override;
  public
    //Creates an object representing the text.
    constructor CreateText(Owner: TJaddNodeOwner; const Text: String);

    //Copies the node to the specified node.
    procedure CopyTo(Compound: TJaddNodeCompound); override;

    property Text: String read FText;
  end;


   { * * *  ***  * * *  ***   TJaddNodeCompound   ***  * * *  ***  * * *  }

  {The abstract base class of all nodes containing other nodes in this simple
   ~[linkUnit UJADDNodes DOM]. }
  TJaddNodeCompound = class(TJaddNode)
  private
    //the list of child nodes
    FChildren: TList;

    //whether following white spaces should be ignored
    //(or whether leading white spaces of the next node should be ignored)
    FIgnoreWhiteSpace: Boolean;

    //Returns the specified child node.
    function GetChild(Index: Integer): TJaddNode;
  protected
    //Returns the remnant of the content of the node as a parameter (ignores
    //formattings etc.).
    function HandleTextAsParameter(const StartText: String;
                                   FirstNodeIndex: Integer): String;

    //Transforms a child node to the more general ~[linkUnit UICNodes COM].
    procedure TransformNode(Node: TJaddNode; ToNode: TICNCompound;
                            DestComment: TICDocComment);

    //Transforms this node to the more general ~[linkUnit UICNodes COM].
    procedure TransformToIC(ToNode: TICNCompound;
                            DestComment: TICDocComment); override;
    //Transforms the remnant of the content of the node to the more general