ucommentdoc.pas

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

    //Checks whether the index is valid for a page of user documentation.
    function PageIndexValid(PageIndex: Integer): Boolean;
    //Gets the (internal) identification (for links) of a page in the user
    //documentation.
    function GetPageURI(PageIndex: Integer): String; virtual;



    //Searches a identifier or file as the target of a link.
    function FindLinkTarget(LinkTarget: String; FindType: TLinkFindType;
                            var Ident: TIdentifier): TPascalFile;
    //Gets a link to an identifier or file in the documentation.
    function GetIdentifierFileLink(const LinkTarget, LinkLabel: String;
                                   FindType: TLinkFindType;
                                   IgnoreNotFound: Boolean = False): String;
    {Writes a link to an identifier or file in the documentation.
    ~param URI       the URI in the documentation to write a link to
    ~param LinkLabel the label for the link; if empty URI is used
    ~result a link to the identifier }
    function InternalLink(const URI, LinkLabel: String): String; virtual;
                                                                 abstract;
    //Writes a link to an external URI.
    function ExternalLink(const URI, LinkLabel: String): String; virtual;



    //Frees all/some links inside the image from the list.
    procedure FreeImageLinks(StartIndex: Integer = 0);
    //Adds a link to the current image.
    procedure AddImageLink(const Link: String; Extern, WholeImage: Boolean;
                           const Position: TRect;
                           const AlternativeText: String);

    {Includes an image in the documentation.
    ~param CharFormat      if the image should be included as a simple
                           character instead of centered in an own paragraph
    ~param JPEGFormat      if the file should be converted to JPEG instead of
                           PNG (only for HTML formats)
    ~param Resolution      resolution to use, (0,0) means auto-detect;
                           only for JPEG images for PDF-generator if no JPEG
                           support is available
    ~param BMP             the image to include or nil
    ~param FileName        the name of the file with the image to include, if
                           BMP is nil
    ~param Links           list of links inside the image
    ~param AlternativeText alternative text/description of the image
    ~result the format to include the image }
    function WriteImage(CharFormat, JPEGFormat: Boolean; Resolution: TPoint;
                        BMP: TBitmap; const FileName: String;
                        Links: TImageLinkList;
                        const AlternativeText: String): String; virtual;
                                                                abstract;




    //Returns the file with an absolute path, if it is relative, the current
    //file is used as its starting position.
    function GetAbsoluteFileName(const FileName: String): String;
    //Reads a file of user documentation; called by ~[code ~~~[[userDoc ~[]].
    function ReadUserDocumentation(FileName: String): Boolean;
    //Returns the section of a comment of an identifier from its counterpart in
    //the parent class.
    function GetInheritedIdentifierDocumentation: String;


    //Returns the current page of user documentation.
    function CurrentUserDocumentationPage(var Name: String): Integer;










    //Adds the message at the current position.
    procedure AddPositionMessage(MsgID: TMessageID; MsgNumber: TMessageNumber;
                                 const MsgText: String); override;



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




    property CommentIdent: TIdentifier read FCommentIdent;
    property CommentFile: TPascalFile read FCommentFile;

    property CurrentHelpContext: Cardinal read FCurrentHelpContext
                                          write FCurrentHelpContext;


    property Evaluator: TCommentEvaluator read FEvaluator
                                          write FEvaluator;
    property GUIHelpReader: TGUIHelpReader read FGUIHelpReader;


    property HelpContextList: TStringList read FHelpContextList;
    property ImageLinks: TImageLinkList read FImageLinks;
  end;







      //the sections to be ignored
const IgnoredCommentSections: array[TIgnoreCommentSection] of TCommentSection =
             (csComment, csParameter,  csResult, csException, csSee,
              csSeeText, csDeprecated, csToDo,   csFeature,   csExample,
              csAuthor,  csVersion);

      //the separator between the topic and the base name when generating help
      //on a GUI
      GUIHelpTopicSeparator = '#';
      //the prefix for special sections of topics when generating help on a GUI
      GUIHelpTopicSpecialPrefix = '.';


implementation

uses SysUtils, IniFiles,
     UFilePaths,
     UPascalConsts,
     UDocumentationTexts,
     UCommentExtraction,
     UInlineCommand,
     UGUIHelpReader;









   { * *  ***  *  ***   TCommentEvaluatorOptionWrapper   ***  *  ***  * *  }

type

  {Allows editing of the options of the evaluator of the comments by wrapping
   it to the defined interface. }
  TCommentEvaluatorOptionWrapper = class(TOptionWrapper)
  private
    //the evaluator to wrap to allow its options to be used
    FEvaluator: TCommentEvaluator;
  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 saves the reference to the evaluator.
    constructor Create(Evaluator: TCommentEvaluator);

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







   { * *  ***  *  ***   TGUIHelpReaderOptionWrapper   ***  *  ***  * *  }


type
  {Allows editing of the options of the extractors of the comments by wrapping
   it to the defined interface. }
  TGUIHelpReaderOptionWrapper = class(TOptionWrapper)
  private
    //the reader of data about a GUI to wrap to allow its options to be used
    FGUIHelpReader: TGUIHelpReader;
  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 saves the reference to the extractor.
    constructor Create(GUIHelpReader: TGUIHelpReader);

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




















   { * *  ***  *  ***   TCommentEvaluatorOptionWrapper   ***  *  ***  * *  }




{Creates the wrapper and save the reference to the evaluator.
~param Evaluator the evaluator whose options should be edited }
constructor TCommentEvaluatorOptionWrapper.Create(Evaluator:
                                                            TCommentEvaluator);
begin
 inherited Create;                     //create the object

 FBaseClass := TCommentEvaluator;      //set base class of all evaluators

 FEvaluator := Evaluator;              //save the reference on the evaluator
end;


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


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


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

 //get the parent class of the evaluator introducing the option
 AClass := TCommentEvaluatorClass(FEvaluator.ClassType);
 while (AClass <> TCommentEvaluator) and
       (TCommentEvaluatorClass(AClass.ClassParent).GetOptionCount > Index) do
  AClass := TCommentEvaluatorClass(AClass.ClassParent);

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

















   { * *  ***  *  ***   TGUIHelpReaderOptionWrapper   ***  *  ***  * *  }



{Creates the wrapper and save the reference to the reader.
~param GUIHelpReader the reader of data about a GUI whose options should be
                     edited }
constructor TGUIHelpReaderOptionWrapper.Create(GUIHelpReader: TGUIHelpReader);
begin
 inherited Create;                     //create the object

 //set base class of all readers of data about a GUI
 FBaseClass := TGUIHelpReader;

 FGUIHelpReader := GUIHelpReader;      //save the reference on the reader
end;


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


{Returns the current class if the options are loaded in a hierarchy.
~result the actual class }
function TGUIHelpReaderOptionWrapper.GetStartClass: TClass;
begin
 Result := FGUIHelpReader.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 }