umakedoc.pas

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

uses SysUtils,
{$IFDEF VER120}
     FileCtrl,
{$ENDIF}
     General,
     UFilePaths,
     UDocumentationTexts;












   { * *  ***  *  ***   TCommentExtractorOptionWrapper   ***  *  ***  * *  }


type
  {Allows editing of the options of the extractors of the comments by wrapping
   it to the defined interface. }
  TCommentExtractorOptionWrapper = class(TOptionWrapper)
  private
    //the extractor to wrap to allow its options to be used
    FExtractor: TCommentExtractor;
  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 extractor.
    constructor Create(Extractor: TCommentExtractor);

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




























  


   { * *  ***  *  ***   TCommentExtractorOptionWrapper   ***  *  ***  * *  }



{Creates the wrapper and save the reference to the extractor.
~param Extractor the extractor whose options should be edited }
constructor TCommentExtractorOptionWrapper.Create(Extractor:
                                                            TCommentExtractor);
begin
 inherited Create;                     //create the object

 FBaseClass := TCommentExtractor;      //set base class of all extractors

 FExtractor := Extractor;              //save the reference on the extractor
end;


{Returns the number of available options.
~result the number of available options }
function TCommentExtractorOptionWrapper.Count: Cardinal;
begin
 Result := FExtractor.GetOptionCount;   //return number of options of extractor
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.) }
procedure TCommentExtractorOptionWrapper.Description(Index: Cardinal;
                                                 var Desc: TOptionDescription);
begin
 FExtractor.GetOptionDescription(Index, Desc); //get description from extractor
end;


{Returns the current class if the options are loaded in a hierarchy.
~result the actual class }
function TCommentExtractorOptionWrapper.GetStartClass: TClass;
begin
 Result := FExtractor.ClassType;
end;


{Gets the value of an option. Call ~[link Description] to get the type and
 the meaning of the option.
~param Index index of the option to get the value of
~result the value of the option }
function TCommentExtractorOptionWrapper.GetOption(Index: Cardinal):
                                                                  TOptionValue;
begin
 Result := FExtractor.GetOption(Index);    //get the option of the extractor
end;

{Sets the value of an option. Call ~[link Description] to get the type and
 the meaning of the option.
~param Index index of the option to set the value
~param Value the new value of the option}
procedure TCommentExtractorOptionWrapper.SetOption(Index: Cardinal;
                                                   const Value: TOptionValue);
begin
 FExtractor.SetOption(Index, Value);       //set the option of the extractor
end;


{Gets the topic of an option, the name of the class of the extractor the option
 is defined in.
~param Index index of the option to get the topic of
~result the topic of the option }
function TCommentExtractorOptionWrapper.Topic(Index: Cardinal): String;
var      AClass          :TCommentExtractorClass; //runner through all classes
begin
 if Index >= FExtractor.GetOptionCount then
  raise EInvalidOption.Create('Invalid index for option supplied!');

 //get the parent class of the extractor introducing the option
 AClass := TCommentExtractorClass(FExtractor.ClassType);
 while (AClass <> TCommentExtractor) and
       (TCommentExtractorClass(AClass.ClassParent).GetOptionCount > Index) do
  AClass := TCommentExtractorClass(AClass.ClassParent);

 Result := AClass.ClassName;                      //return name of the class
end;




















   { * * *  ***  * * *  ***   TCommentExtractor   ***  * * *  ***  * * *  }


{Creates the object and saves the reference on the generator.
~param Generator the generator to extract the comments for }
constructor TCommentExtractor.Create(Generator: TMakeDoc);
begin
 assert(Supports(TMakeDocClass(Generator.ClassType)));

 inherited Create;                          //create the object

 FGenerator := Generator;                   //save the generator
end;

{Frees the object. }
destructor TCommentExtractor.Destroy;
begin
 FOptionAccessor.Free;                      //free the accessor for the options

 inherited Destroy;                         //free the object
end;


{Checks if the extractor can work with the generator.
~param GeneratorClass the class of the generator to check against
~result whether the extractor can extract the comments for generators of that
        class }
class function TCommentExtractor.Supports(GeneratorClass: TMakeDocClass):
                                                                       Boolean;
var            Ancestors        :TClass;
begin
 //generator has to support the comments

 Ancestors := GeneratorClass;

 Result := False;
 while not Result and assigned(Ancestors) and (Ancestors <> TMakeDoc) do
  begin
   Result := Ancestors.ClassNameIs('TCommentDoc') or
             Ancestors.ClassNameIs('TICDocumentDoc');
   Ancestors := Ancestors.ClassParent;
  end;
// Result := GeneratorClass.InheritsFrom(TCommentDoc);
end;


{Returns the number of available options in extractors of this class.
~result the number of available options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function TCommentExtractor.GetOptionCount: Cardinal;
begin
 Result := 0;                        //no options in this abstract class
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.)
~see GetOptionCount }
class procedure TCommentExtractor.GetOptionDescription(Index: Cardinal;
                                                 var Desc: TOptionDescription);
begin
 Assert(False);
 raise EInvalidOption.Create('Invalid index for option supplied!');
end;

{Gets the value of an option. Call ~[link GetOptionDescription] to get the type
 and the meaning of the option.
~param Index index of the option to get the value of
~result the value of the option
~see GetOptionCount
~see GetOptionDescription
~see SetOption }
function TCommentExtractor.GetOption(Index: Cardinal): TOptionValue;
begin
 Assert(False);
 raise EInvalidOption.Create('Invalid index for option supplied!');
end;

{Sets the value of an option. Call ~[link GetOptionDescription] to get the type
 and the meaning of the option.
~param Index index of the option to set the value
~param Value the new value of the option
~see GetOptionCount
~see GetOptionDescription
~see GetOption }
procedure TCommentExtractor.SetOption(Index: Cardinal;
                                      const Value: TOptionValue);
begin
 Assert(False);
 raise EInvalidOption.Create('Invalid index for option supplied!');
end;

{Returns an object to edit the options of the extractor of comments. The object
 must not be freed. ~[inheritDoc]
~result an object to edit the options of the extractor of comments }
function TCommentExtractor.GetOptions: TOptionWrapper;
begin
 if not Assigned(FOptionAccessor) then          //accessor does not exist yet?
  FOptionAccessor := TCommentExtractorOptionWrapper.Create(Self); //create it
 Result := FOptionAccessor;                     //return the wrapper
end;



{Resets the attributes to ready the extractor for a new generation. }
procedure TCommentExtractor.ResetForNewGeneration;
begin

end;



{Returns the additional user documentation in a file.
~param Text the content of the file to be returned as a comment
~result the user documentation as a comment }
function TCommentExtractor.UserDocumentation(Text: String): TComment;
begin
 Result := Sectionize(Text, True);        //just sectionize it
end;

{Returns the comments in a file with documentation as help of a GUI.
~param Text the content of the file to be returned as a comment
~result the documentation of the GUI as a comment }
function TCommentExtractor.GUIHelpDocumentation(Text: String): TComment;
begin
 Result := Sectionize(Text, True);        //just sectionize it
end;




{Sets the names of sections not to be recognized as sections on its own. All
 these section names will not be treated as sections and the name and the
 content will be just part of the previous section. Not all extractors have to
 support this.
~param IgnoredNames the list of ignored section names to be set; can be nil to
                    just test whether the extractor supports this
~result whether this extractor supports the ignoring of sections names }
function TCommentExtractor.SetIgnoredSectionNames(
                                              IgnoredNames: TStrings): Boolean;
begin
 Result := False;                     //not supported by default in extractors
end;


























    //list for the option "IgnoredPortabilityIssues" of the generator
    //~[link TMakeDoc]
var OptionItemsIgnoredPortabilityIssues: TStringList = nil;

    //list for the option "FilterIdentifiersByScope" of the generator
    //~[link TMakeDoc]
    OptionItemsFilterIdentifiersByScope: TStringList = nil;
    //list for the option "FilterIdentifiersByKind" of the generator
    //~[link TMakeDoc]
    OptionItemsFilterIdentifiersByKind: TStringList = nil;
    //list for the option "FilterFunctionsByKind" of the generator
    //~[link TMakeDoc]
    OptionItemsFilterFunctionsByKind: TStringList = nil;











   { * * *  ***  * *  ***   TGeneratorOptionWrapper   ***  * *  ***  * * *  }



type