uicdocumentdoc.pas

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

    procedure SetOption(Index: Cardinal; const Value: TOptionValue); override;






    //Adds the text as a simple text node.
    procedure LocalizeNode(Text: TDocumentationTexts; AddTo: TICNCompound);
    //Returns the current and for the current format escaped text.
    function Localize(Text: TDocumentationTexts): String;
    //Returns the current and for the current format escaped text with the
    //parameters.
    function LocalizeFmt(Text: TDocumentationTexts;
                         const Args: array of const): String;




    //Returns the unique ID of an identifier to be used in the documentation.
    function GetURIOf(Ident: TIdentifier;
                      TheFile: TPascalFile = nil): String; virtual;

    {Gets the (internal) identification (for links) of a topic of documentation
     of a GUI.
    ~param FileIndex  the index of the file
    ~param TopicIndex the index of the topic in the file;
                      -2 for the default topic or -1 for the file itself
    ~result the identification (internal URI) of the topic }
    function GetGUIHelpURIByIndex(FileIndex, TopicIndex: Integer): String;
                                                             virtual; abstract;


    //Returns the help context of the position in the documentation or 0.
    function GetHelpContextOfURI(const URI: String): THelpContext;
    //Returns the position in the documentation with the help context or ''.
    function GetURIOfHelpContext(HelpContext: THelpContext): String;
    //Defines the position to be shown when help is requested with the context.
    procedure DefineHelpContext(const URI: String; HelpContext: THelpContext);
                                                                       virtual;




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


    //Will be called for expressions to add them as (transformed to) nodes.
    procedure AddExpression(const ExprStr: String; OfIdentifier: TIdentifier;
                            AddTo: TICNCompound);


    property ICDocumentDocMessagesID: TMessageID read FICDocumentDocMessagesID;
  end;






      //plural names/texts of the kinds of record-like types
const Plurals: array[TRecordKind] of TDocumentationTexts =
               (dtRecordsHeader,
                dtObjectsHeader, dtClassesHeader,
                dtInterfacesHeader, dtDispInterfacesHeader);




implementation


uses SysUtils,
     General,
     UTokenParser;






   { * * *  ***  * * *  ***   TICDocumentDoc   ***  * * *  ***  * * *  }


    //list for the option "GenerateFileAndClassesTreeFormats" of the generator
    //~[link TICDocumentDoc]
var OptionItemsGenerateFileAndClassesTreeFormats: TStringList = nil;


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



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

 //register messages of this class
 FICDocumentDocMessagesID := RegisterMessages(
                                             ICDocumentDocMessageDescriptions);


 FGenerateFileTreeFiles := True;        //generate all possible files
 FGenerateClassesTreeFiles := True;
 FGenerateFileClassTreeFormats := [Low(TFileClassTreeFileFormat)..
                                   High(TFileClassTreeFileFormat)]
                                  {$IFDEF LINUX} - [fctffEWMF] {$ENDIF};
 FMinLongFunctionLines := 30;           //set minimum length of long functions

 FFileTreeFileBaseName := 'UnitUse';    //set names of the files
 FClassTreeFileBaseName[rkRecord] := DescFilePreFix[rkRecord] + 'List';
 FClassTreeFileBaseName[rkObject] := DescFilePreFix[rkObject] + 'List';
 FClassTreeFileBaseName[rkClass] := DescFilePreFix[rkClass] + 'List';
 FClassTreeFileBaseName[rkInterface] := DescFilePreFix[rkInterface] + 'List';
 FClassTreeFileBaseName[rkDispInterface] := DescFilePreFix[rkDispInterface] +
                                            'List';

 FHelpContextList := TStringList.Create;      //create list for help contexts
 FHelpContextList.Sorted := True;             //list is sorted (faster access)
 FHelpContextList.Duplicates := dupError;     //should not happen!
end;


{Destroys the generator object. }
destructor TICDocumentDoc.Destroy;
begin
 FHelpContextList.Free;                       //free the lists

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

 inherited Destroy;                           //free the object
end;






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








{Returns the number of available options in generators of this class.
~result the number of available "expert"-options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function TICDocumentDoc.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 6;
end;

{Gets a description of an "expert"-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 TICDocumentDoc.GetOptionDescription(Index: Cardinal;
                                                 var Desc: TOptionDescription);
var             PreOptionCount   :Cardinal; //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  inherited GetOptionDescription(Index, Desc)  //forward to parent's method
 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 := 'GenerateFileTreeFiles';
         Desc.Category := 'Generation.Files.Diagrams';
         Desc.Description := 'Whether the files showing the inter-dependence between the files should be generated.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     1: begin
         Desc.Name := 'GenerateClassesTreeFiles';
         Desc.Category := 'Generation.Files.Diagrams';
         Desc.Description := 'Whether the files showing the inheritance tree of classes should be generated.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     2: begin
         Desc.Name := 'GenerateFileAndClassesTreeFormats';
         Desc.Category := 'Generation.Files.Diagrams';
         Desc.Description := 'In what graphic formats the trees of classes and files should be generated.';
         Desc.DataType := otSet;
         Desc.SetNames := OptionItemsGenerateFileAndClassesTreeFormats;
         Desc.DefaultValue.SetData := SetToOption(
                                          [Low(TFileClassTreeFileFormat)..
                                           High(TFileClassTreeFileFormat)]
                                          {$IFDEF LINUX}- [fctffEWMF]{$ENDIF},
                                          SizeOf(TFileClassTreeFileFormats));
        end;
     3: begin
         Desc.Name := 'MinLongFunctionLines';
         Desc.Category := 'Generation';
         Desc.Description := 'The minimum size (number of lines) of the body of functions to be reported as long functions.';
         Desc.DataType := otInteger;
         Desc.DefaultValue.IntData := 30;
        end;
     4: begin
         Desc.Name := 'GenerateHelpContextIniFile';
         Desc.Category := 'Generation.Files';
         Desc.Description := 'Whether an ini file mapping the help contexts to their destinations should be generated.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     5: begin
         Desc.Name := 'GenerateHelpContextMappingFile';
         Desc.Category := 'Generation.Files';
         Desc.Description := 'Whether a simple file containing the mapping from help contexts to the destinations should be created.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
   else
    Assert(Index >= GetOptionCount);       //invalid index!
    raise EInvalidOption.Create('Invalid index for option supplied!');
   end;
  end;
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 TICDocumentDoc.GetOption(Index: Cardinal): TOptionValue;
var      PreOptionCount   :Cardinal;       //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  Result := inherited GetOption(Index)         //forward to parent's method
 else
  begin
   case Index - PreOptionCount of             //depending on index of option
     0: Result.BoolData := FGenerateFileTreeFiles;        //get the value
     1: Result.BoolData := FGenerateClassesTreeFiles;
     2: Result.SetData := SetToOption(FGenerateFileClassTreeFormats,
                                      SizeOf(FGenerateFileClassTreeFormats));
     3: Result.IntData := FMinLongFunctionLines;
     4: Result.BoolData := FGenerateHelpContextIniFile;
     5: Result.BoolData := FGenerateHelpContextMappingFile;
   else
    Assert(Index >= GetOptionCount);          //invalid index!
    raise EInvalidOption.Create('Invalid index for option supplied!');
   end;
  end;
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 TICDocumentDoc.SetOption(Index: Cardinal; const Value: TOptionValue);
var       PreOptionCount   :Cardinal;     //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  inherited SetOption(Index, Value)            //forward to parent's method
 else
  case Index - PreOptionCount of               //depending on index of option
    0: FGenerateFileTreeFiles := Value.BoolData;    //set the value
    1: FGenerateClassesTreeFiles := Value.BoolData;
    2: begin
        OptionToSet(Value.SetData, FGenerateFileClassTreeFormats,
                    SizeOf(FGenerateFileClassTreeFormats));
{$IFDEF LINUX}
        Exclude(FGenerateFileClassTreeFormats, fctffEWMF);
{$ENDIF}
       end;
    3: FMinLongFunctionLines := Value.IntData;
    4: FGenerateHelpContextIniFile := Value.BoolData;
    5: FGenerateHelpContextMappingFile := Value.BoolData;
  else
   Assert(Index >= GetOptionCount);     //invalid index!
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;





{Adds the text as a simple text node.
~param Text  the identifier of the text to localize and add
~param AddTo the node to add the localized text to }
procedure TICDocumentDoc.LocalizeNode(Text: TDocumentationTexts;
                                      AddTo: TICNCompound);
begin
 Assert(Assigned(AddTo));
 AddTo.AppendText(DocumentationTexts[Text].T);
end;

{Returns the current and for the current format escaped text.
~param Text the identifier of the text to localize and return in the current
            format
~result the requested text localized in the current format }
function TICDocumentDoc.Localize(Text: TDocumentationTexts): String;
begin
 Result := HandleRawText(DocumentationTexts[Text].T);
end;

{Returns the current and for the current format escaped text with the
~param Text the identifier of the text containing the format to localize and
            return in the current format
~param Args additional arguments for the text
~result the requested text localized in the current format }
function TICDocumentDoc.LocalizeFmt(Text: TDocumentationTexts;
                                    const Args: array of const): String;
begin
 Result := HandleRawText(Format(DocumentationTexts[Text].T, Args));
end;






{Returns the unique ID of an identifier to be used in the documentation, for
 instance to create a link to it.
~param Ident   the identifier to return a link to (may be nil, to return a link
               to the file)
~param TheFile the file, if it is not an identifier
~result the unique ID of the identifier }
function TICDocumentDoc.GetURIOf(Ident: TIdentifier;
                                 TheFile: TPascalFile = nil): String;
begin
 Assert(Assigned(Ident) <> Assigned(TheFile));
 Assert(not DoNotDocumentIdentifier(Ident, TheFile));

 if Assigned(Ident) then      //identifier in file/record-like type ?
  TheFile := Ident.InFile;      //use its file
 Assert(Assigned(TheFile));