umakedoc.pas

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

  {Allows editing of the options of the generators by wrapping it to the
   defined interface. }
  TGeneratorOptionWrapper = class(TOptionWrapper)
  private
    //the generator to wrap to allow its options to be used
    FGenerator: TMakeDoc;
  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 save the reference to the generator.
    constructor Create(Generator: TMakeDoc);



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














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




{Creates the wrapper and save the reference to the generator.
~param Generator the generator whose options should be edited }
constructor TGeneratorOptionWrapper.Create(Generator: TMakeDoc);
begin
 inherited Create;                     //create the object

 FBaseClass := TMakeDoc;               //set base class of all generators

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



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






{Returns the current class if the options are loaded in a hierarchy.
~result the actual class }
function TGeneratorOptionWrapper.GetStartClass: TClass;
begin
 Result := FGenerator.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 TGeneratorOptionWrapper.GetOption(Index: Cardinal): TOptionValue;
begin
 Result := FGenerator.GetOption(Index);    //get the option of the generator
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 TGeneratorOptionWrapper.SetOption(Index: Cardinal;
                                            const Value: TOptionValue);
begin
 FGenerator.SetOption(Index, Value);       //set the option of the generator
end;





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

 //get the parent class of the generator introducing the option
 AClass := TMakeDocClass(FGenerator.ClassType);
 while (AClass <> TMakeDoc) and
       (TMakeDocClass(AClass.ClassParent).GetOptionCount > Index) do
  AClass := TMakeDocClass(AClass.ClassParent);

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





























   { * * *  ***  * * *  ***   TMakeDoc   ***  * * *  ***  * * *  }

    //the descriptions of messages that can be added in the class
    //~[link TMakeDoc]
var MakeDocMessageDescriptions: TMessageDescriptions = nil;


{Creates the generator object and the list of messages. }
constructor TMakeDoc.Create;
begin
 inherited Create;                  //create object

 FNewLine := LineDelimiter;         //init with default delimiter for system

 FMessages := TGeneratorMessageList.Create; //create the list for the messages

 //register messages of this class
 FMakeDocMessagesID := RegisterMessages(MakeDocMessageDescriptions);

 //create lists to filter files and identifiers
 FFilterFilesByName := TStringList.Create;
 FFilterFilesByName.Sorted := True;               //sort it for faster access
 FFilterFilesByName.Duplicates := dupIgnore;
 FFilterIdentifierByName := TStringList.Create;
 FFilterIdentifierByName.Sorted := True;          //sort it for faster access
 FFilterIdentifierByName.Duplicates := dupIgnore;
end;

{Destroys the list of messages and the generator object. }
destructor TMakeDoc.Destroy;
var        i       :Integer;           //counter through the list to filter
begin
 //free lists to filter files and identifiers
 if Assigned(FFilterIdentifierByName) then
  begin
   for i := 0 to FFilterIdentifierByName.Count - 1 do
    FFilterIdentifierByName.Objects[i].Free;
   FFilterIdentifierByName.Free;
  end;
 FFilterFilesByName.Free;

 FMessages.Free;                    //free the list for the messages
 FOptionAccessor.Free;              //free the accessor for the options

 FExtractor.Free;                   //free extractor of comments

 //unregister messages of this class
 UnRegisterMessages(FMakeDocMessagesID);

 inherited Destroy;                 //free the object
end;





{Sets the list of files to generate documentation about.
~param Value the new list of files }
procedure TMakeDoc.SetFiles(Value: TFileList);
begin
 if FFiles <> Value then                //new parsed data?
  begin
   FFiles := Value;                       //assign the new data
   ParsedDataChanged;                     //notify generator
  end;
end;

{Sets the path to generate the documentation in. Makes sure that there is a
 trailing '\'.
~param Value the new destination path to set }
procedure TMakeDoc.SetDestPath(Value: String);
begin
 //not empty (relative path) and not ending in a (back-)slash?
 if (Value <> '') and not (Value[length(Value)] in ['\', '/']) then
  Value := Value + PathDelimiter;         //append the path delimiter
 FDestPath := Value;                    //set the new path
end;














{Returns the capabilities of this class of the generators.
~result the capabilities of this class of the generators }
class function TMakeDoc.Capabilities: TGeneratorCapabilities;
begin
 Result := [];
end;









{Returns the number of available options in generators of this class.
~result the number of available options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function TMakeDoc.GetOptionCount: Cardinal;
begin
 Result := 13;
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 TMakeDoc.GetOptionDescription(Index: Cardinal;
                                              var Desc: TOptionDescription);
begin
 ClearDescription(Desc);                 //clear structure
 case Index of                           //depending on index of option
   0:  begin                             //set the values describing the option
        Desc.Name := 'DestPath';
        Desc.Category := '';
        Desc.Description := 'The directory, where the documentation should be generated in.';
        Desc.DataType := otString;
        Desc.DefaultValue.StrData := '';
       end;
   1:  begin
        Desc.Name := 'ProjectName';
        Desc.Category := '';
        Desc.Description := 'The name of the project to be included into the documentation.';
        Desc.DataType := otString;
        Desc.DefaultValue.StrData := '';
       end;
   2:  begin
        Desc.Name := 'AutoLaunchDocumentation';
        Desc.Category := 'Postprocessing';
        Desc.Description := 'If the generated documentation should be shown/started after generation.';
        Desc.DataType := otBoolean;
        Desc.DefaultValue.BoolData := False;
       end;
   3:  begin
        Desc.Name := 'OnlyPublicIdentifiers';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'If only public members should be included in the documentation.';
        Desc.DataType := otBoolean;
        Desc.DefaultValue.BoolData := False;
       end;
   4:  begin
        Desc.Name := 'IgnoredPortabilityIssues';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'If identifiers with these portability issues should be excluded from the documentation.';
        Desc.DataType := otSet;
        Desc.SetNames := OptionItemsIgnoredPortabilityIssues;
        Desc.DefaultValue.SetData := 0;
       end;
   5:  begin
        Desc.Name := 'FilterIdentifiersByScope';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'If identifiers with these scopes should be excluded from the documentation.';
        Desc.DataType := otSet;
        Desc.SetNames := OptionItemsFilterIdentifiersByScope;
        Desc.DefaultValue.SetData := 0;
       end;
   6:  begin
        Desc.Name := 'FilterMembersByScope';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'If members with these scopes should be excluded from the documentation.';
        Desc.DataType := otSet;
        Desc.SetNames := OptionItemsFilterMembersByScope;
        Desc.DefaultValue.SetData := 0;
       end;
   7:  begin
        Desc.Name := 'FilterIdentifiersByKind';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'What kinds of identifiers should be excluded from the documentation.';
        Desc.DataType := otSet;
        Desc.SetNames := OptionItemsFilterIdentifiersByKind;
        Desc.DefaultValue.SetData := 0;
       end;
   8:  begin
        Desc.Name := 'FilterClassesByKind';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'What kinds of record-like types should be excluded from the documentation.';
        Desc.DataType := otSet;
        Desc.SetNames := OptionItemsFilterClassesByKind;
        Desc.DefaultValue.SetData := 0;
       end;
   9:  begin
        Desc.Name := 'FilterFunctionsByKind';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'What kinds of functions should be excluded from the documentation.';
        Desc.DataType := otSet;
        Desc.SetNames := OptionItemsFilterFunctionsByKind;
        Desc.DefaultValue.SetData := 0;
       end;
   10: begin
        Desc.Name := 'FilterMembersByKind';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'What kinds of members should be excluded from the documentation.';
        Desc.DataType := otSet;
        Desc.SetNames := OptionItemsFilterMembersByKind;
        Desc.DefaultValue.SetData := 0;
       end;
   11: begin
        Desc.Name := 'FilterFilesByName';
        Desc.Category := 'Generation.Filter';
        Desc.Description := 'A comma-separared list of the names of files that should be excluded from the documentation.';
        Desc.DataType := otString;
        Desc.DefaultValue.StrData := '';
       end;