ujaddcomments.pas

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

    //Returns the value of a variable text at the current position.
    function GetVariableText(const TextName: String;
                             var Text: String): Boolean;
    //Reads the content of a file to be included in the documentation unquoted.
    function ReadRawFile(FileName: String; var Content: String): Boolean;
    //Registers a file with additional user documentation to be included in the
    //documentation.
    function RegisterUserDocumentationFile(FileName: String): Boolean;

    //Tries to inherit documentation for the current position.
    function InheritDocumentation(ToNode: TICNCompound): Boolean; virtual;

    //Returns whether the formatting of the text should be kept in the
    //documentation.
    function KeepFormat: Boolean;

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

    //Returns the absolute path (directory) of the current position or ''.
    function CurrentAbsoluteFilePath: 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);


    property JaddCommentData: TJaddCommentData read FJaddCommentData;
  end;











   { * * *  ***  * * *  ***   TJaddSourceComments   ***  * * *  ***  * * *  }


  //a mapping from a list of identifiers to their comments
  TJaddIdentifierComments = class;

  {The comment of an identifier and the mapping to the comments of its members.
   If it does not have any members the field ~[link Members] may be nil. }
  TJaddIdentifierCommentValue = record
    //the comment of the identifier
    Comment: TJaddComment;
    //the mapping to the comments of the members, may be nil
    Members: TJaddIdentifierComments;
  end;




  {The comment of a file and the mapping to the comments of its identifiers. }
  TJaddFileComments = record
    //the comment of the file
    FileComment: TJaddComment;
    //the mapping to the comments of the identifiers
    IdentifierComments: TJaddIdentifierComments;
  end;

  //The list of comments for each parsed file (and identifier).
  TAllJaddFileComments = array of TJaddFileComments;



  {Holds the comments of all parsed identifiers and files. It defines the
   method ~[link .TransformComments TransformComments] to transform all
   comments to the more general ~[linkUnit UICNodes COM] - Comment Object
   Model. }
  TJaddSourceComments = class(TJaddComments)
  private
    //all comments of all files and identifiers
    FJaddComments: TAllJaddFileComments;


    //used to inherit default documentation/comments for other sections,
    //only as a marker to inherit not existing sections 
    FDefaultInheritSection: TJaddNodeSection;


    //the object that will hold the transformed comments;
    //temporary field, not freed when this object is destroyed!
    FTransformDestComments: TICSourceComments;
    //the list of comments that could not be transformed, because they inherit
    //documentation from not yet transformed comments;
    //temporary field, not freed when this object is destroyed!
    FUnfinishedComments: TList;
    //the currently transformed comment; temporary field
    FCurrentComment: TJaddComment;
    //the currently transformed section; temporary field
    FCurrentSection: TJaddNodeSection;
    //the comment to inherit documentation from; temporary field
    FCurrentInheritComment: TICIdentifierComment;
    //the object to which the comment should be transformed; temporary field
    FCurrentDestComment: TICIdentifierComment;
    //the identifier whose comment is currently transformed,
    //nil when of a file; temporary field
    FCurrentIdentifier: TIdentifier;
    //the file whose comment is currently transformed,
    //nil when of an identifier; temporary field
    FCurrentTheFile: TPascalFile;
    //the index of the parameter whose comment is currently transformed;
    //temporary field
    FCurrentParameterIndex: Integer;



    //Returns the comment of the identifier.
    function GetJaddComment(Identifier: TIdentifier): TJaddComment;
    //Returns the comment of the file.
    function GetJaddFileComment(AFile: TPascalFile): TJaddComment;


    //Reads and parses all comments, each to a simple DOM.
    function ReadAllComments: TAllJaddFileComments;

    //Called when the current position (for a new message) has to be
    //determined.
    procedure GetCurrentPosition(var Position: TDocumentationPosition);

    //Transforms a comment from the simple DOM to the more general COM.
    function TransformComment(Comment: TJaddComment;
                              DestComment: TICIdentifierComment;
                              Identifier: TIdentifier;
                              TheFile: TPascalFile): Boolean;

    //Returns the section to inherit documentation from.
    function GetInheritSection: TICNode;

  public
    //Creates the object and parses all comments to the simple DOM.
    constructor Create(JaddCommentData: TJaddCommentData);
    //Frees the object and all comments (in the simple DOM).
    destructor Destroy; override;


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


    //Transforms all comments from the simple DOM to the more general COM.
    procedure TransformComments(DestComments: TICSourceComments);





    //Tries to inherit documentation for the current position.
    function InheritDocumentation(ToNode: TICNCompound): Boolean; override;

    //The empty line is for testing the automatic inheriting of documentation:

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


    //Returns the absolute path (directory) of the current file or ''.
    function CurrentAbsoluteFilePath: String; override;


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



    property JaddComment[Identifier: TIdentifier]: TJaddComment
                                                           read GetJaddComment;
    property JaddFileComment[AFile: TPascalFile]: TJaddComment
                                                       read GetJaddFileComment;
  end;







   { * * *  ***  * * *  ***   TJaddUserComments  ***  * * *  ***  * * *  }



  {Used to parse files of additional user documentation and transform it. }
  TJaddUserComments = class(TJaddComments)
  private
    //strings are short, unique names of files, objects are index of first
    //page, list is not sorted, entries are in the same order they were added;
    //it is used only in two cases, to make sure no file is read twice, and to
    //get the file path of the "current" file of the current page
    FFiles: TStringList;
    //list is sorted for fast access by the names of the pages (for links),
    //objects are the indices of the pages in ~[link FComments]
    FPageNames: TStringList;
    //the list of pages as ~[link TJaddComment]s
    FComments: TList;

    //the index of the current page to be transformed, -1 for none
    FCurrentPageIndex: Integer;

    //the object to which the additional text for the index of the
    //documentation should be transformed
    FIndexComment: TICSimpleComment;

    //Called when the current position (for a new message) has to be
    //determined.
    procedure GetCurrentPosition(var Position: TDocumentationPosition);

  public
    //Creates the object and the internal lists.
    constructor Create(JaddCommentData: TJaddCommentData);
    //Frees the object and the internal lists.
    destructor Destroy; override;


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

    //Returns the (short unique) name of the file containing the page.
    function FileOfPage(PageIndex: Integer): String;
    //Returns the index of the page (for links).
    function PageByName(const PageName: String): Integer;


    //Reads a file with (additional) user documentation.
    function ReadUserDocFile(const FileName: String): Boolean;


    //Transforms all comments from the simple DOM to the more general COM.
    procedure TransformComments(DestComments: TICUserDocComments);



    //Returns the absolute path (directory) of the current file or ''.
    function CurrentAbsoluteFilePath: String; override;

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

    property IndexComment: TICSimpleComment read FIndexComment
                                            write FIndexComment;
  end;












   { * * *  ***  * * *  ***   TJaddGUIComments  ***  * * *  ***  * * *  }

  {The data about a file of a GUI to generate documentation as a help about. }
  TGUIFileData = record
    //the default comment for not documented components
    FDefaultComment: TJaddGUIComment;
    //a preface to use when generating the documentation
    FPreface: TJaddGUIComment;
    //an epilogue to use when generating the documentation
    FEpilogue: TJaddGUIComment;
    //the documentations of the documented components as
    //~[link TJaddGUIComment];
    //in same order as read from files, as will be in the documentation
    FComments: TList;

    //sorted mapping from the names of the comments to their indices in
    //~[link FComments]
    FCommentMapping: TStringList;
  end;

  //a pointer on the data to be used in the list
  //~[link TJaddGUIComments.FComments]
  PGUIFileData = ^TGUIFileData;



  {Used to parse the data of a GUI and files with the documentation for it
   and to transform the documentation to the ~[linkUnit UICNodes COM]. }
  TJaddGUIComments = class(TJaddComments)
  private
    //the object to hold all data to generate the documentation as a help on a
    //GUI
    FGUIData: TICGUIHelpList;
    //all comments of all files of a GUI as a ~[link PGUIFileData] for each
    //file
    FComments: TList;


    //Checks if the name is an alias and returns the final name.
    function GUIHelpUnalias(PossibleAliasName: String;
                            Data: TICGUIHelpData): String;

    //Generates the linked image of the current file of documentation on a GUI.