ugenerate.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) 2005-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 UGenerate;

{Contains ~[link TGeneratorManager] as a facade for the generation of
 documentation with all its needed objects, i.e. a generator, an extractor
 of comments and an evaluator of those comments so far (others may follow).
}

interface

uses Classes, IniFiles,
     UProgress,
     UBaseIdents,
     UOptions, UGenerationMessages, UGUIHelpIndexContent,
     UMakeDoc, UCommentDoc;



      //name of the option for the name of the file to generate the
      //documentation to (if supported)
const OptionNameFileName = 'FileName';
      //name of the option in the extractor of comments for the special
      //character to split the comments into sections (if supported)
      OptionNameSectionSeparator = 'SectionSeparator';
      //name of the option in the evaluator of comments for the special
      //character to start inline commands with (if supported)
      OptionNameCommandChar = 'CommandChar';
      //name of the option in the evaluator of comments for the special
      //character to start inline commands with after the special command
      //character (if supported)
      OptionNameInlineCommandEndChar = 'InlineCommandEndChar';
      //name of the option in the evaluator of comments for the special
      //character to end inline commands with (if supported)
      OptionNameInlineCommandStartChar = 'InlineCommandStartChar';


type

   { * * *  ***  * * *  ***   TGeneratorManager   ***  * * *  ***  * * *  }


  //a simple extended boolean value, besdes True and False there is also a
  //third state for unknown/ignored/don't care/something inbetween/etc./pp.
  TYesNoMaybe = (
                 ynmYes,        //the option is enabled
                 ynmNo,         //the option is disabled
                 ynmMaybe);     //the option is neither enabled nor disabled


  //a facade for the generation of documentation
  TGeneratorManager = class;


  {An event of the generator manager. Used when one of the objects to generate
   the documentation is changed.
  ~param Sender the generator manager object for which an event occurred }
  TGeneratorManagerEvent = procedure (Sender: TGeneratorManager) of object;



  {A facade for the generation of documentation with all its needed objects,
   i.e. a generator, an extractor of comments and an evaluator of those
   comments so far (others may follow). Although it may be currently more
   complex then the interface of the managed objects themselves. }
  TGeneratorManager = class
  private
    //the generator to use to generate the documentation
    FGenerator: TMakeDoc;

    //the class of the extractors to use to extract the comments of identifiers
    //and files for the documentation
    FExtractorClass: TCommentExtractorClass;
    //the class of the evaluators of texts to include in the documentation
    FEvaluatorClass: TCommentEvaluatorClass;

    //the name of the ini file to initialize the objects with after their
    //creation
    FIniFileName: String;

    //the alternative content for the main index when generating help on a GUI
    FGUIMainIndexRoot: TGUIMainIndexEntry;

    //event handler to call, when the generator changes
    FOnGeneratorChanged: TGeneratorManagerEvent;
    //event handler to call, when the extractor of comments changes
    FOnExtractorChanged: TGeneratorManagerEvent;
    //event handler to call, when the evaluator of texts changes
    FOnEvaluatorChanged: TGeneratorManagerEvent;



    //Access method to get the parsed data.
    function GetParsedData: TFileList;
    //Access method to set the parsed data.
    procedure SetParsedData(Value: TFileList);
    //Access method to get the interface to show the progress.
    function GetProgress: IProgressInterface;
    //Access method to set the interface to show the progress.
    procedure SetProgress(const Value: IProgressInterface);

    //Access method to get the path to generate the documentaton to.
    function GetDestPath: String;
    //Access method to set the path to generate the documentaton to.
    procedure SetDestPath(const Value: String);
    //Access method to get the name/title of the project to include in the
    //documentation.
    function GetProjectName: String;
    //Access method to set the name/title of the project to include in the
    //documentation.
    procedure SetProjectName(const Value: String);
    //Access method to get the name of the file to generate.
    function GetFileName: String;
    //Access method to set the name of the file to generate.
    procedure SetFileName(const Value: String);
    //Access method to get whether the special characters inside comments are
    //set for compatibility with Javadoc.
    function GetUseJavadocCompatibilityCharacters: TYesNoMaybe;
    //Access method to set whether the special characters inside comments are
    //set for compatibility with Javadoc.
    procedure SetUseJavadocCompatibilityCharacters(Value: TYesNoMaybe);





    //Returns the highest common class of the objects.
    function GetCommonClass(Obj1, Obj2: TObject; BaseClass: TClass): TClass;

    //Assigns the common options of the other generator.
    procedure AssignGeneratorOptions(Other: TMakeDoc);
    //Assigns the common options of the other extractor of comments.
    procedure AssignExtractorOptions(Other: TCommentExtractor);
    //Assigns the common options of the other evaluator.
    procedure AssignEvaluatorOptions(Other: TCommentEvaluator);

  public
    //Creates the object to manage the generation.
    constructor Create;
    //Frees the object and the generator.
    destructor Destroy; override;


    //Changes the generator to be used to generate the documentation.
    function ChangeGeneratorByName(const Identification: String): Boolean;
    //Changes the extractor of comments.
    function ChangeExtractorByName(const Identification: String): Boolean;
    //Changes the evaluator.
    function ChangeEvaluatorByName(const Identification: String): Boolean;




    //Generates the documentation.
    function Generate(Files: TStrings): Boolean;
    //Generates the user documentation.
    function GenerateOnlyUserDocumentation(Files: TStrings): Boolean;
    //Generates the user documentation.
    function GenerateGUIHelp(LogFiles: TStrings; Files: TStrings): Boolean;




    //Resets the generator to its default values.
    procedure ResetGenerator;
    //Sets options of the generator from the list.
    procedure GeneratorLoadOptionList(Options: TStrings);
    //Loads the options of the generator from the file.
    procedure GeneratorLoadOptionsFromFile(const FileName: String);
    //Loads the options of the generator from the ini file.
    procedure GeneratorLoadOptionsFromIniFile(Ini: TCustomIniFile);

    //Returns whether a generator is available.
    function GeneratorAvailable: Boolean;
    //Returns the description of the generator.
    function GeneratorDescription: TGeneratorDescription;
    //Returns the name of the class of the generator.
    function GeneratorClassName: String;

    //Returns whether the generator uses extractors.
    function GeneratorUsesCommentExtractors: Boolean;
    //Returns whether the generator uses evaluators.
    function GeneratorUsesCommentEvaluators: Boolean;
    //Returns whether the generator supports (additional) user documentation.
    function GeneratorSupportsUserDocumentation: Boolean;

    //Returns the capabilities of the generator.
    function GeneratorCapabilities: TGeneratorCapabilities;
    //Returns an object to edit the options of the generator.
    function GeneratorOptions: TOptionWrapper;
    //Returns whether the generator writes the documentation to a main file.
    function GeneratorHasFileName: Boolean;
    //Returns the status text of the generator after generation.
    function GetGenerateStatusText: String;
    //Returns the messages of the generator.
    procedure GetGeneratorMessages(Messages: TGeneratorMessageList;
                                   var Descriptions: TMessageDescriptionsList);





    //Resets the extractor of comments to its default values.
    procedure ResetExtractor;
    //Loads the options of the extractor of comments from the file.
    procedure ExtractorLoadOptionsFromFile(const FileName: String);
    //Returns the description of the extractor of comments.
    function ExtractorDescription: TExtractorDescription;
    //Returns the name of the class of the extractor of comments.
    function ExtractorClassName: String;
    //Returns an object to edit the options of the extractor of comments.
    function ExtractorOptions: TOptionWrapper;


    //Resets the evaluator to its default values.
    procedure ResetEvaluator;
    //Loads the options of the evaluator from the file.
    procedure EvaluatorLoadOptionsFromFile(const FileName: String);
    //Returns the description of the evaluator.
    function EvaluatorDescription: TEvaluatorDescription;
    //Returns the name of the class of the evaluator.
    function EvaluatorClassName: String;
    //Returns an object to edit the options of the evaluator.
    function EvaluatorOptions: TOptionWrapper;



    //Returns an object to edit the options of the reader of the data about a
    //GUI.
    function GUIHelpReaderOptions: TOptionWrapper;


    //Returns a list of wrappers for all options of the different objects.
    function AllOptions: TOptionWrapperList;
    //Loads the options from the ini file and sets them from the list.
    procedure InitAllOptions(Ini: TCustomIniFile; Options: TStrings);
    //Sets an option of one of the generator objects.
    procedure SetOneOption(const Name, Value: String);





    property TheGenerator: TMakeDoc read FGenerator;

    property GUIMainIndexRoot: TGUIMainIndexEntry read FGUIMainIndexRoot;

    property MainIniFileName: String read FIniFileName write FIniFileName;

    property ParsedData: TFileList read GetParsedData write SetParsedData;
    property Progress: IProgressInterface read GetProgress write SetProgress;

    property DestPath: String read GetDestPath write SetDestPath;
    property ProjectName: String read GetProjectName write SetProjectName;
    property FileName: String read GetFileName write SetFileName;
    property UseJavadocCompatibilityCharacters: TYesNoMaybe
                                    read GetUseJavadocCompatibilityCharacters
                                    write SetUseJavadocCompatibilityCharacters;


    property OnGeneratorChanged: TGeneratorManagerEvent
                            read FOnGeneratorChanged write FOnGeneratorChanged;
    property OnExtractorChanged: TGeneratorManagerEvent
                            read FOnExtractorChanged write FOnExtractorChanged;
    property OnEvaluatorChanged: TGeneratorManagerEvent
                            read FOnEvaluatorChanged write FOnEvaluatorChanged;
  end;







implementation

uses SysUtils,
     UCommentExtraction,   //for the list of all extractors
     UInlineCommand;       //for the list of all evaluators






   { * * *  ***  * * *  ***   TGeneratorManager   ***  * * *  ***  * * *  }


{Creates the object to manage the generation. }
constructor TGeneratorManager.Create;
begin
 inherited Create;                  //create the object

 //create the root of the alternative content for the main index
 FGUIMainIndexRoot := TGUIMainIndexEntry.Create;
end;


{Frees the object and the generator. }
destructor TGeneratorManager.Destroy;
begin
 //free the root of the alternative content for the main index
 FGUIMainIndexRoot.Free;

 FGenerator.Free;                   //free the generator

 inherited Destroy;                 //free the object
end;




{Access method to get the parsed data.
~result the parsed data }
function TGeneratorManager.GetParsedData: TFileList;
begin
 Result := FGenerator.Files;
end;

{Access method to set the parsed data.
~param Value the new parsed data }
procedure TGeneratorManager.SetParsedData(Value: TFileList);
begin
 FGenerator.Files := Value;
end;

{Access method to get the interface to show the progress.
~result the interface to show the progress }