ujaddcomments.pas

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

    property UsePathLinks: Boolean read FUsePathLinks;
    property ParameterNamesAsSections: Boolean read FParameterNamesAsSections;
    property AllowAutoInheritComment: Boolean read FAllowAutoInheritComment
                                              write FAllowAutoInheritComment;
    property GUIHelpUseAutoAliases: Boolean read FGUIHelpUseAutoAliases
                                            write FGUIHelpUseAutoAliases;
    property GUIHelpUseTopicAsLinkText: Boolean read FGUIHelpUseTopicAsLinkText
                                              write FGUIHelpUseTopicAsLinkText;


    property KeepTextFormatting: Boolean read FKeepTextFormatting
                                         write FKeepTextFormatting;
    property InUserDoc: Boolean read FInUserDoc write FInUserDoc;

    property SourceComments: TJaddSourceComments read FSourceComments
                                                 write FSourceComments;
    property UserDocComments: TJaddUserComments read FUserDocComments;
    property GUIComments: TJaddGUIComments read FGUIComments write FGUIComments;
  end;










   { * * *  ***  * * *  ***   TCommentsJaddNodeOwner  ***  * * *  ***  * * *  }

  {The owner for nodes in the simple ~[linkUnit UJADDNodes DOM]. It
   reimplements the standard owner to provide extended information to the nodes
   via virtual methods when transforming them to the ~[linkUnit UICNodes COM].
   So this owner mainly reimplements virtual methods and in most cases the
   calls are just redirected to the object holding all the comments,
   ~[linkClass TJaddComments], which will handle them. }
  TCommentsJaddNodeOwner = class(TJaddNodeOwner)
  private
    //list of comments that contain the comment this owner's nodes are part of
    FComments: TJaddComments;
    //the comment the nodes of this owner are part of
    FComment: TJaddComment;

  public
    //Creates the owner of the nodes and saves the references.
    constructor Create(Comments: TJaddComments; Comment: TJaddComment);

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

    //Returns the contents of a defined text by its name.
    function GetDefinedText(const TextName: String): TJaddNode; override;
    //Starts defining a text by its name.
    function StartDefineText(const TextName: String): TJaddNodeCompound;
                                                                      override;
    //Ends defining a text and registers it so it can be read again.
    procedure EndDefineText(const TextName: String;
                            Text: TJaddNodeCompound); override;
    //Returns the value of a variable text at the current position.
    function GetVariableText(const TextName: String;
                             var Text: String): Boolean; override;
    //Reads the content of a file to be included in the documentation unquoted.
    function ReadRawFile(const FileName: String;
                         var Content: String): Boolean; override;
    //Registers a file with additional user documentation to be included in the
    //documentation.
    function RegisterUserDocumentationFile(const FileName: String): Boolean;
                                                                      override;
    //Sets the help context for the current comment.
    procedure SetHelpContext(HelpContext: THelpContext); override;
    //Tries to inherit documentation for the current position.
    function InheritDocumentation(ToNode: TICNCompound): Boolean; override;
    //Returns whether text should be inserted pre-formatted (as-is) in the
    //documentation.
    function GetPreformattedState: Boolean; override;
    //Returns the index of the parameter with the specified name or -1.
    function FindParameterIndex(const ParameterName: String): Integer;
                                                                      override;
    //Sets the index of the parameter whose documentation is currently
    //transformed.
    procedure SetCurrentParameterIndex(ParamIndex: Integer); override;

    //Searches an identifier by its name (possibly with its ~[em path]).
    procedure FindIdentifier(const Name: String; Kind: TFindIdentifierKind;
                             Links: TList); override;
    //Returns the index of the page of user documentation to link to.
    function SearchLinkPage(const PageName: String): Integer; override;
    //Returns the destination in the help on a GUI to link to.
    function SearchLinkGUI(const GUILink: String;
                           var CommentIndex: Integer): Integer; override;
    //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; override;

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

    //Adds a message to the generator.
    procedure AddMessage(Msg: TJaddNodeMessages; const Text: String); override;
  end;







   { * * *  ***  * * *  ***   TJaddComment   ***  * * *  ***  * * *  }


//  TCommentAttribute = (caDeprecated, caToDo, caFeature, caBug,
//                       caForceEvent, caForceProperty,
//                       caHasExample);
//  TCommentAttributes = set of TCommentAttribute;


  //defines where comments to inherit documentation from should be searched
  TInheritKind = (
                  //inherit only from the super class,
                  //used when manual ~~[inheritDoc ] inline command is used
                  ikOnlySuperClass,
                  //default, inherit from anywhere,
                  //used for all classes and members that are not documented
                  //and for properties for which also the documentation of the
                  //field (or method) used for reading it is considered
                  ikDefaultComment);

  //defines where comments to inherit documentation from should be searched
  TInheritKinds = set of TInheritKind;




  {The comment of an identifier or file. It contains a list of all the sections
   in the comment and saves the help context. }
  TJaddComment = class
  private
    //the object for freeing all nodes of this comment
    FOwnership: TJaddNodeOwner;
    //where documentation should be inherited from to be included in the
    //documentation generated from this comment
    FInheritsComment: TInheritKinds;
    //the whole comment as text
    FWholeText: String;
    //the list of all ~[link TJaddNodeSection sections] in the comment
    FSections: TList;
    //the help context of the documentation generated from this comment
    FHelpContext: THelpContext;


    //Returns the number of sections in this comment.
    function GetSectionCount: Integer;
    //Returns a section of this comment.
    function GetSection(Index: Integer): TJaddNodeSection;

  public
    //Creates the comment and the list of sections.
    constructor Create;
    //Creates the comment and the owner of its nodes.
    constructor CreateWithOwner(Comments: TJaddComments);
    //Frees the comment, the list of sections and all nodes.
    destructor Destroy; override;

    //Adds a section to the comment.
    procedure AddSection(Content: TJaddNodeSection);



    property Ownership: TJaddNodeOwner read FOwnership write FOwnership;

    property InheritsComment: TInheritKinds read FInheritsComment
                                            write FInheritsComment;

    property SectionCount: Integer read GetSectionCount;
    property Sections[Index: Integer]: TJaddNodeSection read GetSection;

    property WholeText: String read FWholeText write FWholeText;
    property HelpContext: THelpContext read FHelpContext write FHelpContext;
  end;




   { * * *  ***  * * *  ***   TJaddUserComment   ***  * * *  ***  * * *  }


  {A comment representing a page of user documentation. It contains only one
   section, of kind ~[link csPage], the content of the page. }
  TJaddUserComment = class(TJaddComment)
  private
    //the name of the page of user documentation this comment represents
    FPageName: String;
    //the index of the page of user documentation this comment represents
    FPageIndex: Integer;
    //the title of the page of user documentation
    FPageTitle: String;

  public
    //Creates the comment of the page of user documentation
    constructor Create(const PageName: String; PageIndex: Integer;
                       const PageTitle: String);
    //Creates the comment of the page of user documentation and the owner of
    //its nodes.
    constructor CreateWithOwner(Comments: TJaddComments;
                                const PageName: String; PageIndex: Integer;
                                const PageTitle: String);

    property PageName: String read FPageName;
    property PageIndex: Integer read FPageIndex;
    property PageTitle: String read FPageTitle;
  end;



   { * * *  ***  * * *  ***   TJaddGUIComment   ***  * * *  ***  * * *  }

  {A comment representing a topic of a component in the help of a GUI. It
   contains only one section, of kind ~[link csGUI], the content of the
   topic. }
  TJaddGUIComment = class(TJaddComment)
  private
    //the name of the topic this comment represents
    FName: String;
    //the title of the topic
    FTitle: String;
    //whether the comment has been referenced (by links inside the
    //documentation)
    FReferenced: Boolean;

  public
    //Creates the comment of the help on a GUI.
    constructor Create(const Name, Title: String);
    //Creates the comment of the help on a GUI and the owner of its nodes.
    constructor CreateWithOwner(Comments: TJaddComments;
                                const Name, Title: String);

    property Name: String read FName;
    property Title: String read FTitle;
    property Referenced: Boolean read FReferenced write FReferenced;
  end;











   { * * *  ***  * * *  ***   TJaddComments   ***  * * *  ***  * * *  }


  {The more or less abstract base class of all classes holding comments in the
   format of this program. This class is not abstract per se, but it does not
   hold any comments, so it does not make much sense to create an object of it.
   But it is actually used as a parent object for (the owners of) defined
   texts. It is needed so it can forward requests for information to the main
   object of class ~[linkClass TJaddCommentData].

   Most methods in this class are actually used to request additional
   information, in most cases these requests are simply forwarded to the main
   object of class ~[linkClass TJaddCommentData]. Some are also just not
   implemented and add a warning message when called, they are reimplemented in
   the child classes. }
  TJaddComments = class
  protected
    //the main object for parsing and transforming comments in the format of
    //this program
    FJaddCommentData: TJaddCommentData;



    //Removes any double special characters that have to be quoted (with
    //themselves) so they are not interpreted as the beginning of a new
    //section.
    function UnquoteSpecialChar(const Text: String): String;
    //Returns the name of the page of user documentation or comment about a
    //GUI.
    function ExtractPageName(var Text: String): String;
    //Returns the title of the page of user documentation or comment about a
    //GUI.
    function ExtractPageTitle(var Text: String): String;
    //Generates a warning for every residual section in a comment.
    procedure CheckInvalidSections(Comment: TComment);


    //Parses the text of a section to a simple DOM.
    procedure ParseSectionText(NewSection: TJaddNodeSection;
                               Text: String; Comment: TJaddComment);

  public
    //Creates the object and saves the reference on the main object.
    constructor Create(JaddCommentData: TJaddCommentData);

    //Resets the attributes to ready the list of comments for a new generation.
    procedure ResetForNewGeneration; virtual;


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

    //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);