ujaddnodes.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) 2006-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 UJADDNodes;

interface

{Contains classes for a simple DOM - Document Object Model - used to represent
 comments in the format at used by this program (like this one). It is similar
 to the ~[linkUnit UICNodes COM] - Comment Object Model - which is used to
 represent the final comment, but this DOM is much simpler because it is used
 only temporarily and then transformed to the COM - which is a more general
 representation.

 The reason for all this is, to ease the parsing of comments in different
 styles/formats. Every comment has just to be transformed into the COM, the whol
 e handling of JADD-specific comments has been out-sourced in only about three
 files. These are mainly this file with the ~[em nodes] of the DOM and the unit
 ~[link UJADDComments] containing classes to hold the comments of all
 identifiers and files and the options how to parse the comments and tranform
 them to the COM. If someone wants to parse comments in a different style,
 either another temporary DOM can be used or directly the COM can be created.

 As with the COM, all nodes are "owned" by an instance of the class
 ~[link TJaddNodeOwner] to make sure all nodes are freed eventually. The nodes
 are sub-classes of the abstract base class ~[link TJaddNode], but the class
 hierarchy is much smaller, there are only three concrete classes.
 ~[link TJaddNodeText] contains the real content of the comments, their texts,
 while ~[link TJaddNodeInlineCommand] represents a special command inside the
 comment, it will encapsulate other nodes. And the DOM is even simpler, the
 third class, ~[link TJaddNodeSection], can only be used at top-level of the
 DOM.
}


uses Windows, Classes,
     UBaseIdents,
     UImages,
     UComments,
     UILComment, UICNodes;


type
  //At some point in the future the old generators will be removed.
  //Then the declaration of these types might be moved here or somewhere else.

  //Sections in comments to comment specific parts of the identifiers etc..
  TJaddSection = UComments.TCommentSection;

  //These are the inline commands available in the comments.
  TJaddInlineCommand = (
                        //no command, just use the text
                        jicNone,

                        //Adds both values and inserts the result instead.
                        jicAdd,
                        //Forces a new line/a line break.
                        jicLineBreak,
                        //Formats the text as code.
                        jicCode,
                        //Defines a text to a symbolic name.
                        jicDefineText,
                        //Defines a text to a symbolic name if two strings are
                        //in arequired relationship.
                        jicDefineTextIf,
                        //Creates a diagram and inserts it into the
                        //documentation.
                        jicDiagram,
                        //Emphasizes the text.
                        jicEmphasize,
                        //Defines the help context for the current topic.
                        jicHelpContext,
                        //Adds an image to the documentation.
                        jicImage,
                        //Creates a link in the current image.
                        jicImageLink,
                        //Includes a file of low level codes of the current
                        //format.
                        jicIncludeFile,
                        //Inherits the documentation of the current identifier
                        //and section from the parent class.
                        jicInheritDoc,
                        //Inserts a defined text by a symbolic name.
                        jicInsertText,
                        //Inserts a variable text, its value depending on the
                        //position where it is used.
                        jicInsertVariable,
                        //Creates a link to an identifier.
                        jicLink,
                        //Creates a link to an identifier of a class.
                        jicLinkClass,
                        //Creates a link to an URI.
                        jicLinkExtern,
                        //Creates a link inside the currently generating help
                        //on a GUI.
                        jicLinkGUI,
                        //Creates a link to a page in the user documentation.
                        jicLinkPage,
                        //Creates a link to a file.
                        jicLinkUnit,
                        //Forces a new paragraph to start.
                        jicParagraph,
                        //Formats the text preformatted, i.e. as code, and
                        //preserves the indentation and multiple spaces.
                        jicPreFormatted,
                        //Formats the code as a small sample of code.
                        jicSample,
                        //Reads the file as part of the user documentation.
                        jicUserDoc,

                        //replaces its content, the name of the option, with
                        //either "True" or "False" depending on whether one of
                        //the objects used to generate the documentation
                        //supports the option
                        jicOptionSupported,
                        //replaces its content, the name of the option, with
                        //the value of the option of one of the objects used to
                        //generate the documentation as a text, the empty text
                        //will be used if the option is unknown
                        jicOptionValue,



                        //This command may be inserted automatically when no
                        //comment has been given at all. It is similar to
                        //~[link jicInheritDoc] but the comment may be inherited
                        //from different sources (i.e. for properties from
                        //their read-attribute)
                        jicInheritDefaultComment
                        );


      //the first inline command in the enumeration that can appear in the
      //comments
const jicFirstRealInlineCommand = Succ(jicNone);
      //the last inline command in the enumeration that can appear in the
      //comments
      jicLastRealInlineCommand = Pred(jicInheritDefaultComment);
                                 //jicUserDoc;

      //all inline commands creating a link (should not be nested!)
      JaddInlineCommandLinks = [jicLink, jicLinkClass, jicLinkExtern,
                                jicLinkGUI, jicLinkPage, jicLinkUnit];


      //all the inline commands that don't have parameters
      JaddInlineCommandWithoutParameters = [jicLineBreak, jicInheritDoc,
                                            jicParagraph];


type

  //Variable texts, that can be queried by ~[code ~~~[[insertVariable~[]].
  //Their resulting texts depend on the position where they are queried.
  //If they are not applicable at the requested position, an empty text will be
  //used.
  TVariables = (
                //column in that the current identifier has been defined in
                vDefinitionColumn,
                //line in that the current identifier has been defined in
                vDefinitionLine,
                //(internal) name of current file
                vFileName,
                //size of file (may differ from actual size (#13#10 problem))
                vFileSize,
                //kind of current file (unit, program, library or package)
                vFileType,
                //column in that the current identifier has been first defined
                //in
                vForwardDefinitionColumn,
                //line in that the current identifier has been first defined in
                vForwardDefinitionLine,
                //number of lines in the file
                vNumberOfLines,
                //the current identifier, whose documentation is currently
                //evaluated, transformed or generated
                vThisIdentifier,
                //if the current identifier, whose documentation is currently
                //evaluated or generated, is a class this value will evaluate
                //to the same name, if it is a member, it will evaluate to the
                //class it is a member of
                vThisClass,
                //number of the current page in the user documentation
                vThisPage,
                //name of the current page in the user documentation
                vThisPageName);









  {The messages that can be generated while parsing comments in the format of
   this program, evaluating inline commands or transforming the comments to the
   ~[linkUnit UICNodes COM] - Comment Object Model. }
  TJaddNodeMessages = (
                       //a single command character (~~) was encountered; at
                       //the level when parsing the comments, it has either to
                       //be followed by the character to start an inline
                       //command ([) or by another command character, which
                       //means it is simply quoted
                       jcmSingleCommandChar,
                       //an inline command hasn't been closed, i.e. the comment
                       //ended before the closing bracket (]) has been found
                       jcmUnclosedInlineCommand,
                       //an unknown inline command has been encountered,
                       //possible a typing error
                       jcmUnknownInlineCommand,

                       //no comment has been found for the identifier or file
                       //(or the main comment is empty)
                       jcmNoCommentFound,
                       //no comment has been found for the class or class
                       //member (or its main comment is empty); the program is
                       //trying to inherit the comment from the super class
                       jcmNoCommentFoundTryingToInherit,

                       //additional text has been found in an inline command,
                       //but it allows no text at all or only some limited
                       //parameters
                       jcmTextAfterEndOfInlineCommand,
                       //an inline command has been specified as a parameter
                       //for another inline command, but the inner one is
                       //invalid as parameter
                       jcmInvalidInlineCommandAsParameter,
                       //an inline command needs a(nother) parameter, but the
                       //inline command ended before finding it
                       jcmParameterMissingForInlineCommand,
                       //the name of a defined text or the name of a variable
                       //text to be inserted is invalid
                       jcmInvalidTextVariableName,
                       //a file with raw documentation to be inserted unquoted
                       //couldn't be found
                       jcmRawDocumentationFileNotFound,
                       //a file with additional user documentation couldn't be
                       //found
                       jcmFileOfUserDocNotFound,
                       //the documentation of an identifier couldn't be
                       //inherited from the super class
                       jcmNoDocumentationToInherit,
                       //the ancestor of an identifier couldn't be found while
                       //searching for it to inherit the documentation from it;
                       //more specific an identifier of a different kind was
                       //found, what should not be possible
                       jcmInvalidIdentWhileSearchingAncestorIdent,
                       //an invalid section has been found (f.i. the return
                       //value of a function has been documented more then
                       //once)
                       jcmInvalidSection,
                       //a section needs a parameter, but the section ended
                       //before finding the parameter
                       jcmParameterMissingForSection,
                       //the name of a parameter to be documented is invalid,
                       //either it does not exist for the
                       //function/function type or it has already been
                       //documented
                       jcmInvalidNameOfFunctionParameter,
                       //a link has been found inside another link
                       jcmLinkInsideLink,
                       //the target of a link could not be found
                       jcmLinkTargetNotFound,
                       //an inline command has been found inside another inline
                       //command and this combination is invalid
                       jcmInlineCommandInvalidInOtherInlineCommand,
                       //an image link has been found outside an image
                       jcmImageLinkNotDirectlyInImageInlineCommand,
                       //an image (or diagram) has been found inside another
                       //image (no, this is no image-processing application)
                       jcmImageInAnotherImage,
                       //an image (or diagram) has been found inside another
                       //inline command, images can't be formatted (no, this is
                       //no image-processing application) and links have to be
                       //created inside the image with image link
                       jcmImageInAnotherInlineCommand,
                       //the file of an image to be included in the
                       //documentation couldn't be found
                       jcmImageFileNotFound,
                       //a link inside an image is of an invalid format or
                       //specifies invalid data