ucommentscanner.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) 2007-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 UCommentScanner;

{Contains the abstract base class of all scanners of comments that will
 generate the comments in the ~[linkUnit UICNodes COM] - Comment Object
 Model -, the class ~[link TCommentScanner]. }

interface

uses Classes,
     UOptions,
     UGenerationMessages,
     UILComment, UICGUIHelpData,
     UICDocumentDoc;




   { * *  ***  *  ***   TCommentScanner   ***  *  ***  * *  }

type
  //the class of a scanner
  TCommentScannerClass = class of TCommentScanner;


  {Called when the current position (for a new message) has to be determined.
  ~param Position the variable to set the positon in (it has been cleared
                  before calling the procedure) }
  TGetPositionCallBack = procedure(var Position: TDocumentationPosition)
                                                                     of object;



  {Abstract base class of all scanners of comments that will generate the
   comments in the ~[linkUnit UICNodes COM] - Comment Object Model. }
  TCommentScanner = class
  private
    //the generator for which the comments are read and transformed
    FGenerator: TICDocumentDoc;


    //call back to get the current position (for messages)
    FOnGetPosition: TGetPositionCallBack;

    //an object to access the options of the scanner of comments through a more
    //general interface
    FOptionAccessor: TOptionWrapper;


    //the extension of the screenshots of GUIs which are documented as a help
    //for them
    FGUIScreenShotExtension: String;
  public
    //Creates the object to scan comments and transform them to the COM.
    constructor Create(Generator: TICDocumentDoc); virtual;
    //Frees the object and the accessor of options.
    destructor Destroy; override;



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


    //Returns an object to edit the options of this object.
    function GetOptions: TOptionWrapper;



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





    {Reads and prepares the comments of all identifiers and files, user
     documentation and/or help of a GUI.
    ~param UserDocumentationFiles the files with (additional) user
                                  documentation to be read
    ~param GUIHelp                if ~[link FGenerator.GenerationKind] =
                                  ~[link UMakeDoc.dgkGUIHelp dgkGUIHelp], the
                                  list of parsed log files of a GUI to generate
                                  the documentation about as a help
    ~param KeepLineBreaks         whether the format (text-layout) of the
                                  comments should be kept in the final
                                  documentation
    ~param UserCommentIndex       the node to add additional text for the index
                                  of the documentation or the index of the user
                                  documentation to }
    procedure PrepareComments(UserDocumentationFiles: TStrings;
                              GUIHelp: TICGUIHelpList;
                              KeepLineBreaks: Boolean;
                              UserCommentIndex: TICSimpleComment); virtual;
                                                                   abstract;

    {Transforms the comments of all identifiers and files to the
     ~[linkUnit UICNodes COM].
    ~param Destination    the object to which all the comments should be
                          transformed to
    ~param KeepLineBreaks whether the format (text-layout) of the comments
                          should be kept in the final documentation }
    procedure TransformSourceComments(Destination: TICSourceComments;
                                      KeepLineBreaks: Boolean); virtual;
                                                                abstract;
    {Transforms the comments as help on a GUI to the
     ~[linkUnit UICNodes COM]. }
    procedure TransformGUIHelp; virtual; abstract;
    {Transforms the (pages of the) additional user documentation to the
     ~[linkUnit UICNodes COM].
    ~param Destination the object to which the comments should be transformed
                       to }
    procedure TransformUserDocumentation(Destination: TICUserDocComments);
                                                             virtual; abstract;



    property Generator: TICDocumentDoc read FGenerator;
    property OnGetPosition: TGetPositionCallBack read FOnGetPosition
                                                 write FOnGetPosition;

    property GUIScreenShotExtension: String read FGUIScreenShotExtension;
  end;









//The list of all scanner of comments.
//Contains the names of the classes of the scanners and references to the
//classed themselves in the corresponding objects.
var CommentScannerClasses: TStringList = nil;

//Add a scanner to the list of scanners.
procedure AddCommentScannerClass(CommentScannerClass: TCommentScannerClass);

//Returns the default scanner of comments to be used.
function DefaultScannerClass: TCommentScannerClass;


implementation

{$IFOPT C+}

uses UJADDComments;  //only included so it is initialized before any
                     //generator using it

{$ENDIF}




   { * *  ***  *  ***   TCommentScannerOptionWrapper   ***  *  ***  * *  }

type

  {Allows editing of the options of the scanner and transformer of comments by
   wrapping it to the defined interface. }
  TCommentScannerOptionWrapper = class(TOptionWrapper)
  private
    //the scanner and transformer of comments to wrap to allow its options to
    //be used
    FCommentScanner: TCommentScanner;
  protected
    //Returns the current class if the options are loaded in a hierarchy.
    function GetStartClass: TClass; override;

    //Gets the value of an option.
    function GetOption(Index: Cardinal): TOptionValue; override;
    //Sets the value of an option.
    procedure SetOption(Index: Cardinal; const Value: TOptionValue); override;
  public
    //Creates the wrapper and saves the reference to the scanner of comments.
    constructor Create(CommentScanner: TCommentScanner);

    //Returns the number of available options.
    function Count: Cardinal; override;
    //Gets a description of an option.
    procedure Description(Index: Cardinal;
                          var Desc: TOptionDescription); override;

    //Gets the topic of an option.
    function Topic(Index: Cardinal): String; override;
  end;




   { * *  ***  *  ***   TCommentScannerOptionWrapper   ***  *  ***  * *  }


{Creates the wrapper and saves the reference to the scanner of comments.
~param CommentScanner the scanner of comments whose options should be edited }
constructor TCommentScannerOptionWrapper.Create(CommentScanner:
                                                              TCommentScanner);
begin
 inherited Create;                     //create the object

 FBaseClass := TCommentScanner;        //set (base) class of all scanners

 FCommentScanner := CommentScanner;    //save the reference on the scanner
end;


{Returns the number of available options.
~result the number of available options }
function TCommentScannerOptionWrapper.Count: Cardinal;
begin              //return number of options of scanner
 Result := FCommentScanner.GetOptionCount;
end;

{Gets a description of an option.
~param Index index of the option to get data of