umakedoc.pas

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

   ~[linkClass UDocumentDoc.TDocumentDoc], that implements general methods
   needed for generating documentation.~[br]
   This class implements the general interface, messages, options of generators
   and some general methods about parsed data that may be called by
   subclasses.

   ~[diagram TMakeDoc.tree
             /layout=post /size=8 /margin=5 /members /ShowFile=False] }
  TMakeDoc = class(TTextFormat)
  private
    //object to show the progress of the generation of the documentation
    FProgress: IProgressInterface;

    //the object to use to get the comments
    FExtractor: TCommentExtractor;

    //the characters to be used to separate lines/start a new line
    FNewLine: String;

    //the descriptions of all possible messages
    FMessageDescriptions: TMessageDescriptionsList;
    //the list of messages generated while generating the documentation
    FMessages: TGeneratorMessageList;
    //called when a message is generated
    FOnMessage: TGeneratorMessageEvent;

    //additional status messages after successful generation
    FStatusText: String;



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


    //ID of the messages of this class
    FMakeDocMessagesID: TMessageID;


    //if the generated help should be launched after generation (if supported)
    FAutoLaunchDocumentation: Boolean;


    //whether only public members should be included in the documentation
    FNoPrivateOnlyInterface: Boolean;
    //identifiers with these portability issues won't be included in the
    //documentation
    FIgnoredPortabilityIssues: TIdentPortabilities;

    //filter identifier that are declared in a file by the file and their
    FFilterIdentifiersByScope: TSpecialFileScopes;             //position in it
    //filter members of classes by their scope
    FFilterMembersByScope: set of TMemberScope;
    //filter identifiers in files by their kind
    FFilterIdentifiersByKind: set of TFilterIdentifierKinds;
    //filter record-like types by the kind of type
    FFilterClassesByKind: set of TRecordKind;
    //filter functions and methods by their kind
    FFilterFunctionsByKind: set of TFunctionKind;
    //filter members by their kind
    FFilterMembersByKind: set of TMemberKind;



    //name of files to filter, sorted
    FFilterFilesByName: TStringList;
    //names of identifiers to filter, sorted;
    //object may contain a TStringList again, if only identifiers in special
    //contexts are filtered, lists are also sorted;
    //
    //to check: search identifier in this list,
    //not found: document it, found and no sub-list: ignore;
    //has sub-list: search record-like type in sub-list, if not found search
    //"file.recordtype", if in no record-like type search directly file; ignore
    //if found
    FFilterIdentifierByName: TStringList;



    //Sets the list of files to generate documentation about.
    procedure SetFiles(Value: TFileList);
    //Sets the path to generate the documentation in. Makes sure that there is
    //a trailing '\'.
    procedure SetDestPath(Value: String);
  protected
    //the kind of documentation generated by the generator;
    //is set by calling one of the public generation methods
    FGenerationKind: TDocGenerationKind;


    //the list of parsed pascal data to generate documentation about;
    //won't be freed by the generator
    FFiles: TFileList;



    //directory (with trailing "\") to generate the documentation in
    FDestPath: String;

    //the name/the title of the project
    FProjectName: String;











    //Checks each identifier, if there is a field without a scope before it.
    procedure CheckForUnscopedFieldsObject(List: TIdentifierList);
    //Checks each inheritance-tree, if there is a field without a set scope.
    procedure CheckForUnscopedFieldsClass(List: TStrings);



    //Gets all inherited identifiers of that kind.
    procedure GetInheritedList(BaseClass: TRecordType;
                               List: TIdentifierList;
                               WhatClass: TIdentifierClass);










    //Gets all identifiers and files with the given portability issue.
    procedure GetPortabilityIdents(List: TIdentifierFileList;
                                   PortabilityIssue: TIdentPortability;
                                   ListToAdd: TIdentifierFileList = nil);

    //Generates a sorted list of all identifiers and files.
    procedure GetAllIdentifiersAndFiles(List: TIdentifierFileList);
    //Gets the list of all exported (and documented) identifiers (functions).
    procedure GetAllExports(List: TIdentifierList);
    //Adds all functions that are at least as long as the specified number of
    //lines.
    procedure GetAllFunctionsLongerThan(List: TIdentifierList; Lines: Integer);







    //Creates the directory in which the documentation will be generated.
    procedure CreateDocumentationDirectory;




    //Called when the parsed data, the list of files is changed.
    procedure ParsedDataChanged; virtual;



    //Reinitializes any strings depending on current localization settings.
    procedure ResetLanguageStrings; virtual;

    {Process parsed data; for instance generate some documentation about it.
    ~result whether the documentation has been successfully generated and
            generation hasn't been aborted }
    function DoGenerateDocumentation: Boolean; virtual; abstract;

    //Decides how to generate the documentation.
    function GenerateDocumentationWith(const Info:
                                              TGenerationInformation): Boolean;
                                                                       virtual;


    property MakeDocMessagesID: TMessageID read FMakeDocMessagesID;
    property NoPrivateOnlyInterface: Boolean read FNoPrivateOnlyInterface;
    property FilterIdentifiersByScope: TSpecialFileScopes
                                                read FFilterIdentifiersByScope;            
    property AutoLaunchDocumentation: Boolean read FAutoLaunchDocumentation;
    property IgnoredPortabilityIssues: TIdentPortabilities
                                                read FIgnoredPortabilityIssues;
  public
    //Creates the generator object.
    constructor Create; virtual;
    //Destroys the generator object.
    destructor Destroy; override;




    {Returns a description of the documentation of the generator.
    ~result a description of the documentation of the generator }
    class function GetDescription: TGeneratorDescription; virtual; abstract;

    //Returns the capabilities of this class of the generators.
    class function Capabilities: TGeneratorCapabilities; virtual;



    //Returns the number of available options in generators of 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; const Value: TOptionValue); virtual;


    //Returns an object to edit the options of the generator.
    function GetOptions: TOptionWrapper;
    //Returns a list of wrappers for all options of the generator and all used
    //objects.
    function GetAllOptions: TOptionWrapperList; virtual;
    //Adds all wrappers for all options of the different objects to the list.
    procedure AddOptionWrappers(const List: TOptionWrapperList); virtual;





    //Registers a list of messages.
    function RegisterMessages(Descriptions: TMessageDescriptions;
                              MayAlreadyBeRegistered: Boolean = False):
                                                                    TMessageID;
    //Registers all registered message to the other generator.
    function RegisterAllMessagesTo(OtherGenerator: TMakeDoc):
                                                        TMessageDescriptionMap;
    //Unregisters a list of messages.
    procedure UnRegisterMessages(Messages: TMessageID);


    //Adds the message.
    procedure AddMessage(Message: TGeneratorMessage);
    //Adds a simple message.
    procedure AddSimpleMessage(MsgID: TMessageID; MsgNumber: TMessageNumber;
                               const MsgText: String);
    //Adds the message at the current position.
    procedure AddPositionMessage(MsgID: TMessageID; MsgNumber: TMessageNumber;
                                 const MsgText: String); virtual;
    //Adds the message at the specified position.
    procedure AddMessageWithPosition(MsgID: TMessageID;
                                     MsgNumber: TMessageNumber;
                                     const MsgText: String;
                                     const Position: TDocumentationPosition);
    //Adds the message and calls back to let the position set.
    procedure AddMessageWithRemotePosition(MsgID: TMessageID;
                                 MsgNumber: TMessageNumber;
                                 const MsgText: String;
                                 SetPos: TGeneratorMessageSetPositionCallBack);
                                                                       virtual;
    //Adds the message at the identifier (or file).
    procedure AddIdentifierMessage(MsgID: TMessageID;
                                   MsgNumber: TMessageNumber;
                                   const MsgText: String;
                                   Identifier: TIdentifier;
                                   TheFile: TPascalFile);


    //Returns the messages of the generator.
    procedure GetMessages(Messages: TGeneratorMessageList;
                          var Descriptions: TMessageDescriptionsList);






    //Checks whether the identifier should be included in the documentation.
    function DoNotDocumentIdentifier(Ident: TIdentifier;
                                     TheFile: TPascalFile = nil): Boolean;
                                                                       virtual;
    //Checks whether the file should be included in the documentation.
    function DoNotDocumentFile(TheFile: TPascalFile): Boolean;

    //Searches the identifier.
    function FindIdentifier(const LongIdentName: String; TheFile: TPascalFile;
                            EndPosition: TPosition): TIdentifier;
    //Searches the implemented interface of a property or aliased method.
    function FindPropertyInterface(const InterfName: String;
                                   TheClass: TRecordType): TIdentifier;


    //Loads a graphic and returns it as a bitmap.
    function TransformFileToBitmap(const FileName: String): TBitmap;



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

    //Process parsed data; for instance generate some documentation about it.
    function GenerateDocumentation(const Info:
                                              TGenerationInformation): Boolean;








    //Searches the identifier.
    function FindIdentifierByName(const LongIdentName: String;
                                  TheFile: TPascalFile): TIdentifier;



    property Files: TFileList read FFiles write SetFiles;

    property Progress: IProgressInterface read FProgress write FProgress;
    property Extractor: TCommentExtractor read FExtractor write FExtractor;

    property GenerationKind: TDocGenerationKind read FGenerationKind;


    property NewLine: String read FNewLine write FNewLine;

    property ProjectName: String read FProjectName write FProjectName;
    property DestPath: String read FDestPath write SetDestPath;
    property StatusText: String read FStatusText write FStatusText;

    property OnMessage: TGeneratorMessageEvent read FOnMessage
                                               write FOnMessage;


 {
    property OptionCount: Cardinal read GetOptionCount;
    property Options[Index: Cardinal]: TOptionValue read GetOption
                                                    write SetOption;
}
  end;








      //plural names/texts of the kinds of record-like types
const PluralsInternal: array[TRecordKind] of String =
                            ('Records', 'Objects',
                             'Classes', 'Interfaces', 'Dispatch-Interfaces');
      //prefixes for internal names for identifiers of record-like types
      DescFilePreFix: array[TRecordKind] of String =
                            ('Record', 'Object',
                             'Class', 'Interface', 'DispInterface');






//The list of all generators of documentation.
//Contains the names of the classes of the generators and references to the
//classed themselves in the corresponding objects.
var GeneratorClasses: TStringList = nil;

//Add a generator to the list of generators.
procedure AddGeneratorClass(GeneratorClass: TMakeDocClass);


    //list for the option "FilterClassesByKind" of the generator
    //~[link TMakeDoc]
var OptionItemsFilterClassesByKind: TStringList = nil;
    //list for the option "FilterMembersByKind" of the generator
    //~[link TMakeDoc]
    OptionItemsFilterMembersByKind: TStringList = nil;
    //list for the option "FilterMembersByScope" of the generator
    //~[link TMakeDoc]
    OptionItemsFilterMembersByScope: TStringList = nil;



implementation