usourcecommentextraction.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) 2003-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 USourceCommentExtraction;


{Contains the class to extract comments for the generators of documentation
 from directly above the declaration of the identifiers in the source code,
 ~[link TSourceCommentExtractor].
}


interface

uses Classes,
{$IFNDEF NOREGULAREXPRESSIONS}
     RegExpr,
{$ENDIF}
     UBaseIdents,
     UOptions,
     UMakeDoc, UComments,
     UCommentExtraction;



type


   { * * *  ***  * *  ***   TSourceCommentExtractor   ***  * *  ***  * * *  }


   //the action to do if comments have a special marker
   TCommentMarkerAction = (
                           //there are no markers in the comments, just use all
                           //the comments as they are written
                           cmaNoMarker,
                           //there is a marker defined for the comments to be
                           //used in the documentation, ignore all other
                           //comments and remove the marker before using the
                           //marked ones
                           cmaUseOnlyMarked,
                           //all comments should be used, but for some a marker
                           //may be used, if that is the case it has to be
                           //removed
                           cmaUseAllRemoveMarker);



  {Extracts comments for the generators of documentation from directly above
   the declaration of the identifiers in the source code. }
  TSourceCommentExtractor = class(TSectionExtractor)
  private
    //if comments of identifiers should be ignored
    FIgnoreIdentifierComments: Boolean;
    //if comments of files should be ignored
    FIgnoreFileComments: Boolean;

    //if the file comment after the first statement/token should be used
    FFileCommentAfterFirstStatement: Boolean;
    //if comments at the foward declararation should be used instead at the
    //complete declaration
    FGetForwardComments: Boolean;
    //if comment not found at the position given by ~[link
    //FGetForwardComments], whether it should be searched at the other position
    FFallBackToOtherPositionForComment: Boolean;

    //ignore comments not starting with a star "*"
    FUseOnlyStaredComments: Boolean;
    //the marker for comments to be used in the documentation
    FCommentMarker: String;
    //the action to do if comments have a special marker
    FCommentMarkerAction: TCommentMarkerAction;
    //whether between the beginning of the comment and the marker white spaces
    //may be
    FCommentMarkerAfterWhiteSpace: Boolean;


    //whether tabulator characters should be transformed to spaces, like the
    //Delphi IDE does by default
    FTransformTabToSpaces: Boolean;
    //the width of a tabulator character (the distances between tab-stops)
    FTabulatorWidth: Integer;
    //whether whitespaces at the end of lines should be removed, like the
    //Delphi IDE does by default
    FRemoveTrailingWhiteSpaces: Boolean;

    //remove leading stars at the beginning of the comment and each line of it
    FRemoveLeadingStars: Boolean;
    //remove trailing stars at the end of the comment
    FRemoveTrailingStars: Boolean;

{$IFNDEF NOREGULAREXPRESSIONS}
    //object to filter the content of comment if
    //~[link FCommentRegExprContentIndex] <> 0
    FCommentRegExprFilter: TRegExpr;
    //index of sub-expression in ~[link FCommentRegExprFilter] with content
    //of the comment; 0 to disable filtering
    FCommentRegExprContentIndex: Integer;
    //object to filter the content of each line of a comment if
    //~[link FCommentRegExprPerLineContentIndex] <> 0
    FCommentRegExprPerLineFilter: TRegExpr;
    //index of sub-expression in ~[link FCommentRegExprPerLineFilter] with
    //content of the comment in the line; 0 to disable filtering
    FCommentRegExprPerLineContentIndex: Integer;
{$ENDIF}



  protected
    //Removes leading stars at the beginning of the text and each line of it.
    function RemoveLeadingStars(Text: String): String;
    //Removes trailing stars at the end of the text.
    function RemoveTrailingStars(const Text: String): String;



    //Returns the processed comment.
    function ProcessComment(Text: String): TComment;

  public
    //Creates the object and saves the reference on the generator.
    constructor Create(Generator: TMakeDoc); override;
    //Frees the object.
    destructor Destroy; override;



    //Returns a description of the extractor of comments.
    class function GetDescription: TExtractorDescription; override;


    //Returns the number of available options in extractors of this class.
    class function GetOptionCount: Cardinal; override;
    //Gets a description of an option.
    class procedure GetOptionDescription(Index: Cardinal;
                                         var Desc: TOptionDescription);
                                                                      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;




    //Returns the comments about the identifier.
    function Comment(Ident: TIdentifier): TComment; override;
    //Returns the comments about the file.
    function CommentOfFile(AFile: TPascalFile): TComment; override;


    //Returns the additional user documentation in a file.
    function UserDocumentation(Text: String): TComment; override;
    //Returns the comments in a file with documentation as help of a GUI.
    function GUIHelpDocumentation(Text: String): TComment; override;
  end;













implementation

uses SysUtils;








    //list for the option "CommentMarkerAction" of the extractor
    //~[link TSourceCommentExtractor]
var CommentMarkerActionEnumerationList: TStringList = nil;


   { * * *  ***  * *  ***   TSourceCommentExtractor   ***  * *  ***  * * *  }


{Creates the object and saves the reference on the generator.
~param Generator the generator to extract the comments for }
constructor TSourceCommentExtractor.Create(Generator: TMakeDoc);
begin
 inherited Create(Generator);                  //create the object

{$IFNDEF NOREGULAREXPRESSIONS}
 FCommentRegExprFilter := TRegExpr.Create;     //create objects to use regexps
 FCommentRegExprFilter.ModifierR := False;
 FCommentRegExprFilter.Expression := '^(.*)$';

 FCommentRegExprPerLineFilter := TRegExpr.Create;
 FCommentRegExprPerLineFilter.ModifierR := False;
 FCommentRegExprPerLineFilter.Expression := '^(.*)$';
{$ENDIF}

 FCommentMarkerAction := cmaNoMarker;          //set some defaults
 FFileCommentAfterFirstStatement := True;
 FFallBackToOtherPositionForComment := True;
 FTransformTabToSpaces := True;
 FTabulatorWidth := 8;
 FRemoveTrailingWhiteSpaces := True;
end;

{Frees the object. }
destructor TSourceCommentExtractor.Destroy;
begin
{$IFNDEF NOREGULAREXPRESSIONS}
 FCommentRegExprPerLineFilter.Free;            //free objects for regexps
 FCommentRegExprFilter.Free;
{$ENDIF}

 inherited Destroy;                            //free the object
end;







{Returns a description of the extractor of comments.
~result a description of the extractor of comments }
class function TSourceCommentExtractor.GetDescription: TExtractorDescription;
begin
 Result.Name := 'Source (JADD)';
 Result.Identification := 'JADDSource';
 Result.Description := 'Extracts the comments from the source code directly above the identifiers.';
end;


{Returns the number of available options in extractors of this class.
~result the number of available options }
class function TSourceCommentExtractor.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 18;
end;

{Gets a description of an option.
~param Index index of the option to get data of
~param Desc  out: the description of the option (name, type, default value,
                  etc.) }
class procedure TSourceCommentExtractor.GetOptionDescription(Index: Cardinal;
                                                 var Desc: TOptionDescription);
var             PreOptionCount   :Cardinal;     //number of inherited options
begin
 PreOptionCount := inherited GetOptionCount;    //get number of inherited ones
 if Index < PreOptionCount then                 //asked for inherited option?
  inherited GetOptionDescription(Index, Desc)     //forward to parent class
 else
  begin
   ClearDescription(Desc);               //clear structure
   case Index - PreOptionCount of        //depending on index of option
     0:  begin                           //set the values describing the option
          Desc.Name := 'IgnoreIdentifierComments';
          Desc.Category := 'Comments.Find';
          Desc.Description := 'Ignore all comments on identifiers (useful if not commented for DelphiDoc).';
          Desc.DataType := otBoolean;
         end;
     1:  begin
          Desc.Name := 'IgnoreFileComments';
          Desc.Category := 'Comments.Find';
          Desc.Description := 'Ignore all comments on files (useful if not commented for DelphiDoc).';
          Desc.DataType := otBoolean;
         end;
     2:  begin
          Desc.Name := 'GetForwardComments';
          Desc.Category := 'Comments.Find';
          Desc.Description := 'Get comments from the forward-declaration instead of the full declaration of identifiers (types and functions) if possible.';
          Desc.DataType := otBoolean;
         end;
     3:  begin
          Desc.Name := 'FallBackToOtherPositionForComment';
          Desc.Category := 'Comments.Find';
          Desc.Description := 'If comment at the position of an identifier not found, try its forward declaration or vice versa.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         end;
     4:  begin
          Desc.Name := 'FileCommentAfterFirstStatement';
          Desc.Category := 'Comments.Find';
          Desc.Description := 'Get the comments on files after the first statement (after unit, program, etc.) (f.i. to skip legal comments).';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         end;
     5:  begin
          Desc.Name := 'UseOnlyStaredComments';
          Desc.Category := 'Comments.Filter';
          Desc.Description := 'Ignores comments if they do not start with a star "*".';
          Desc.DataType := otBoolean;
         end;
     6:  begin
          Desc.Name := 'RemoveLeadingStars';
          Desc.Category := 'Comments.Extract';
          Desc.Description := 'Removes leading stars in comments like used by other similar documentation tools.';
          Desc.DataType := otBoolean;
         end;
     7:  begin
          Desc.Name := 'RemoveTrailingStars';
          Desc.Category := 'Comments.Extract';
          Desc.Description := 'Removes trailing stars in comments like used to emphasize the comment.';
          Desc.DataType := otBoolean;
         end;
     8:  begin
          Desc.Name := 'CommentPattern';
          Desc.Category := 'Comments.Extract';
          Desc.Description := 'Regular Expression to extract the content from the comments, the number of the sub-expression to use is set via "CommentPatternContentIndex".';
          Desc.DataType := otString;
  {$IFDEF NOREGULAREXPRESSIONS}
          Desc.Options := [ooNoRead, ooNoWrite];
  {$ENDIF}