ujaddcomments.pas

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

    procedure GenerateGUIHelpImage(Data: TICGUIHelpData);
    //Checks whether all documentation topics in the help for a GUI are used.
    procedure CheckGUIDocumentationTopicUsage;




    //Parses the sections with data of documentation to generate help on a GUI.
    procedure ParseSections(Data: TICGUIHelpData; JaddData: PGUIFileData;
                            const FileName: String; Comment: TComment);
    //Reads a file of documentation for the help on a GUI.
    function ReadFile(Data: TICGUIHelpData; JaddData: PGUIFileData;
                      const FileName: String;
                      ParsedFiles: TStringList): String;
    //Reads the documentation for the help on a GUI.
    procedure ReadDocumentation(Data: TICGUIHelpData);


    //Called when the current position (for a new message) has to be
    //determined.
    procedure GetCurrentPosition(var Position: TDocumentationPosition);
  public
    //Creates the object and the internal lists.
    constructor Create(JaddCommentData: TJaddCommentData;
                       GUIData: TICGUIHelpList);
    //Frees the object and the internal lists with all comments.
    destructor Destroy; override;


    //Gets the position (for links) of a topic of documentation of a GUI.
    function GetGUIHelpPosition(Target: String;
                                var Index: Integer): Integer;


    //Reads all documentation files and parses their comments to the simple
    //DOM.
    procedure ReadAllComments;
    //Transforms all comments from the simple DOM to the more general COM.
    procedure TransformComments;

    //Returns the absolute path (directory) of the current file or ''.
    function CurrentAbsoluteFilePath: String; override;
  end;














{$DEFINE StaticKeyMapTemplateDoNotEndType}
{$UNDEF StaticKeyMapTemplateFreeKeyList}
{$UNDEF StaticKeyMapTemplateValueIsObject}
{$DEFINE StaticKeyMapTemplateInitializeItems}
{$UNDEF StaticKeyMapTemplateValueFree}

  //the keys for the template map to use
  TStaticKeyMapTemplateKey = TIdentifier;
  //the list of keys for the template map to use
  TStaticKeyMapTemplateKeys = TIdentifierListAdapter;
  //the values for the template map to use
  TStaticKeyMapTemplateValue = TJaddIdentifierCommentValue;

{$INCLUDE ..\..\General\Templates\StaticKeyMapTemplate.inc}

  //a map from identifiers to their comments
  TJaddIdentifierComments
{$INCLUDE ..\..\General\Templates\StaticKeyMapTemplate.inc}

  public
    //Free all items and if applicable the keys list.
    destructor Destroy; override;
  end;

  //alias for the map to be used by the implementations of the methods
  TStaticKeyMapTemplate = TJaddIdentifierComments;





  


      //sorted list of texts whose values depend on the position
const VariableNames: array[TVariables] of String =
                     ('DefinitionColumn', 'DefinitionLine',
                      'FileName', 'FileSize', 'FileType',
                      'ForwardDefinitionColumn', 'ForwardDefinitionLine',
                      'NumberOfLines',
                      'ThisIdentifier', 'ThisClass',
                      'ThisPage', 'ThisPageName');


      //the names of the options to change the names of the sections in the
      //comments 
const InlineCommandOptionNames: array[jicFirstRealInlineCommand..
                                      jicLastRealInlineCommand] of String =
   ('Addition',        'LineBreak',      'Code',        'DefineText',
    'DefineTextIf',    'Diagram',        'Emphasize',   'HelpContext',
    'Image',           'ImageLink',      'IncludeFile', 'InheritDocumentation',
    'InsertText',      'InsertVariable', 'Link',        'LinkToClass',
    'LinkExternal',    'LinkToGUI',      'LinkPage',    'LinkToUnit',
    'Paragraph',       'Preformatted',   'Sample',      'UserDocumentation',
    'OptionSupported', 'OptionValue');


implementation

uses SysUtils,

     General,
     UFilePaths,

     UPascalConsts,
     UExtIdents,

     UDocumentationTexts,

     UImages,

     UCommentExtraction;






   { * * *  ***  * * *  ***   TJaddCommentData   ***  * * *  ***  * * *  }


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


      //the number of options in this class of parsers and transformers of
      //comments without the names of the inline command
const OptionCountWithoutInlineCommands = 11;


{Creates the object to manage all comments in the format of this program.
~param Generator the generator for which the comments should be read and
                 transformed }
constructor TJaddCommentData.Create(Generator: TICDocumentDoc);
var         varTexts        :TVariables;      //counter for each variable text
            First           :Integer;         //index of first option to be set
            //counter through inline commands
            i               :TJaddInlineCommand;
            Value           :TOptionValue;    //value to set option with
begin
 inherited Create(Generator);                //create the object

 //register messages of this class
 FJaddCommentMessagesID := Generator.RegisterMessages(
                                               JaddCommentMessageDescriptions);

 //create object to relay request of defined texts
 FDefinedTextsComments := TJaddComments.Create(Self);
 FDefinedTexts := TStringList.Create;         //create list for defined texts

 FVariableTexts := TStringList.Create;        //create list for variable texts
 FVariableTexts.Sorted := True;
 FVariableTexts.Duplicates := dupError;
 //add handlers for the variable texts
 for varTexts := Low(varTexts) to High(varTexts) do
  RegisterVariableText(VariableNames[varTexts], Ord(varTexts));


 //FSourceComments: TJaddSourceComments;
 FUserDocComments := TJaddUserComments.Create(Self);

 FCommandChar := DefaultSectionSeparatorChar; //initialize option values
 FICStartChar := DefaultInlineCommandStart;
 FICEndChar := DefaultInlineCommandEnd;
// FDontParseText := False;
 FEmptyCommentLinesBreakParagraphs := True;
 FUsePathLinks := True;
// FParameterNamesAsSections := False;
 FOptionalCommandParameterBraces := True;
// FKeepTextFormatting := False;
 FAllowAutoInheritComment := True;
 FGUIHelpUseAutoAliases := True;
 FGUIHelpUseTopicAsLinkText := True;


 //create list for names of inline command
 FInlineCommandNames := TStringList.Create;
 FInlineCommandNames.Sorted := True;          //for faster access sort it
 FInlineCommandNames.Duplicates := dupError;  //duplicates are handled manually

 //get index of first option of the names of the inline command
 First := inherited GetOptionCount + OptionCountWithoutInlineCommands -
          Cardinal(Ord(Low(InlineCommandOptionNames)));
 for i := Low(InlineCommandOptionNames) to        //set all default names
          High(InlineCommandOptionNames) do
  begin
   Value.StrData := DefaultInlineCommandNames[i];
   SetOption(First + Ord(i), Value);
  end;
end;

{Frees the object and all comments. }
destructor TJaddCommentData.Destroy;
var        i               :Integer;        //counter through defined texts
begin
 FSourceComments.Free;                      //free all comments
 FUserDocComments.Free;
 FGUIComments.Free;

 FInlineCommandNames.Free;                  //free names of the inline commands

// FReadUserDocFiles.Free;
 FVariableTexts.Free;                       //free registered variable texts
 if Assigned(FDefinedTexts) then
  begin
   for i := 0 to FDefinedTexts.Count - 1 do //free all defined texts
    TJaddNode(FDefinedTexts.Objects[i]).Owner.Free;
   FDefinedTexts.Free;                      //and the list itself
  end;
 FDefinedTextsComments.Free;                //and the object relaying requests

 if Assigned(Generator) then
  //unregister messages of this class
  Generator.UnRegisterMessages(FJaddCommentMessagesID);

 inherited Destroy;                         //free the object
end;








{Returns the number of available options in scanner of comments of this class.
~result the number of available options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function TJaddCommentData.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + OptionCountWithoutInlineCommands +
           Cardinal(Ord(jicLastRealInlineCommand) -
                    Ord(jicFirstRealInlineCommand) + 1);

end;


//const InlineCommandOptionNames: array[jicFirstRealInlineCommand..
//                                      jicLastRealInlineCommand] of String =


{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 TJaddCommentData.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
   Dec(Index, PreOptionCount);         //get index of local option
   case Index of                       //depending on index of option
     0:  begin                           //set the values describing the option
          Desc.Name := 'CommandChar';
          Desc.Category := 'Comments.Commands';
          Desc.Description := 'The character that starts inline commands.';
          Desc.DataType := otString;
          Desc.StrMaxLen := 1;
          Desc.DefaultValue.StrData := DefaultSectionSeparatorChar;
         end;
     1:  begin
          Desc.Name := 'InlineCommandStartChar';
          Desc.Category := 'Comments.Commands';
          Desc.Description := 'The character that starts an inline command after the "CommandChar".';
          Desc.DataType := otString;
          Desc.StrMaxLen := 1;
          Desc.DefaultValue.StrData := DefaultInlineCommandStart;
         end;
     2:  begin
          Desc.Name := 'InlineCommandEndChar';
          Desc.Category := 'Comments.Commands';
          Desc.Description := 'The character that ends an inline command.';
          Desc.DataType := otString;
          Desc.StrMaxLen := 1;
          Desc.DefaultValue.StrData := DefaultInlineCommandEnd;
         end;
     3:  begin
          Desc.Name := 'DontParseComments';
          Desc.Category := 'Comments';
          Desc.Description := 'Don''t parse the comments, just treat them as general comment without special characters and sections.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := False;
         end;
     4:  begin
          Desc.Name := 'EmptyCommentLinesBreakParagraphs';
          Desc.Category := 'Comments';
          Desc.Description := 'An empty line inside a comments starts a new paragraph.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         end;
     5:  begin
          Desc.Name := 'UsePathLinks';
          Desc.Category := 'Comments.Commands';
          Desc.Description := 'Whether links on identifiers with empty text should use a link for each part of its used path instead of only a single on all; whether links without text should be split for each component.';