uiccommentdoc.pas

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

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

    //Adds all wrappers for all options of the different objects to the list.
    procedure AddOptionWrappers(const List: TOptionWrapperList); override;




    //Gets the (internal) identification (for links) of a page in the user
    //documentation.
    function GetPageURI(PageIndex: Integer): String; virtual;
    //Gets the (internal) identification (for links) of topics of documentation
    //of a GUI.
    function GetGUIHelpURIByIndex(FileIndex, TopicIndex: Integer): String;
                                                                      override;

    {Includes an image in the documentation.
    ~param CharFormat      whether the image should be included as a simple
                           character instead of centered in an own paragraph
    ~param JPEGFormat      whether 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;



    //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 ICCommentDocMessagesID: TMessageID read FICCommentDocMessagesID;

    property CommentScanner: TCommentScanner read FCommentScanner;

    property Comments: TICSourceComments read FComments;
    property UserComments: TICUserDocComments read FUserComments;
    property GUIHelpData: TICGUIHelpList read FGUIHelpData;

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

    property KeepRawLineBreaks: Boolean read GetKeepRawLineBreaks;
  end;







implementation

uses SysUtils;




   { * * *  ***  * * *  ***   TICCommentDoc   ***  * * *  ***  * * *  }


    //list for the option "DocumentationSectionsFilter" of the generator
    //~[link TICCommentDoc]
var OptionItemsDocumentationSectionsFilter: TStringList = nil;




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



{Creates the generator object and the helper objects. }
constructor TICCommentDoc.Create;
begin
 inherited Create;                            //create the generator object

 //register messages of this class
 FICCommentDocMessagesID := RegisterMessages(ICCommentDocMessageDescriptions);

 //create the scanner of the comments
 FCommentScanner := DefaultScannerClass.Create(Self);
 //create the builder of the documentation
 FDocumentationBuilder := TICIdentDocBuilder.Create(Self);

 FCurrentUserDocPage := -1;                   //not in user documentation

 FGUIHelpUseTopicAsKeyWords := True;          //initialize options
 FGenerateDocumentationOnDemand := True;
end;

{Destroys the generator object and the different lists. }
destructor TICCommentDoc.Destroy;
begin
 FGUIHelpData.Free;                //free data about GUI to generate help about
 FUserComments.Free;               //free the other comments
 FComments.Free;

 if Assigned(FMainIndexContent) then
  begin
   FMainIndexContent.Owner.Free;   //free alternative content
   FMainIndexContent := nil;       //for main index
  end;

 FDocumentationBuilder.Free;       //free the builder of the documentation
 FCommentScanner.Free;             //free the parser of the comments

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

 inherited Destroy;                //free the generator object
end;



{Returns the number of available options in generators of this class.
~result the number of available options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function TICCommentDoc.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 3;
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 TICCommentDoc.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 := 'KeepLineBreaksInComments';
          Desc.Category := 'Comments.Extract';
          Desc.Description := 'Preserves the line breaks of comments (be sure not to make any line breaks in inline commands when using this option).';
          Desc.DataType := otBoolean;
         end;
     1:  begin
          Desc.Name := 'DocumentationSectionsFilter';
          Desc.Category := 'Generation.Filter';
          Desc.Description := 'Filters some sections of the documentation (mostly lists).';
          Desc.DataType := otSet;
          Desc.SetNames := OptionItemsDocumentationSectionsFilter;
         end;
     2:  begin
          Desc.Name := 'GUIHelpUseTopicAsKeyWords';
          Desc.Category := 'GUIHelp';
          Desc.Description := 'Whether the headings of the help topics instead of the internal component names should be used as key words for the generated documentation as help on a GUI.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         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 TICCommentDoc.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 := FKeepLineBreaksInComments; //get the value
     1: Result.SetData := SetToOption(FDocumentationSectionsFilter,
                                      SizeOf(FDocumentationSectionsFilter));
     2: Result.BoolData := FGUIHelpUseTopicAsKeyWords;
   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 TICCommentDoc.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: FKeepLineBreaksInComments := Value.BoolData; //set the value
    1: OptionToSet(Value.SetData, FDocumentationSectionsFilter,
                                  SizeOf(FDocumentationSectionsFilter));
    2: FGUIHelpUseTopicAsKeyWords := Value.BoolData;
  else
   Assert(Index >= GetOptionCount);            //invalid index!
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;



{Adds all wrappers for all options of the different objects to the list.
~param List the list to add all option wrappers to }
procedure TICCommentDoc.AddOptionWrappers(const List: TOptionWrapperList);
var       Index        :Integer;          //counter through the list

 {Searches the next free entry in the list. }
 procedure NextFreeEntry;
 begin
  //find next free entry
  while assigned(List[Index]) and (Index < Length(List)) do
   inc(Index);
  if Index = Length(List) then
   raise ERangeError.Create('No free entry in list for option wrapper!');
 end;

begin
 inherited AddOptionWrappers(List);     //add inherited options

 Index := 0;                            //start search at the beginning (again)
 NextFreeEntry;                         //search a free entry
 List[Index] := FCommentScanner.GetOptions;  //add options of comment scanner
 NextFreeEntry;                         //search a free entry
 //add options of builder of the documentation of identifiers and files
 List[Index] := FDocumentationBuilder.GetOptions;
end;







{Gets the (internal) identification (for links) of a page in the user
 documentation.
~param PageIndex the number of the page (-1 for index)
~result the identification (internal URI) of the page }
function TICCommentDoc.GetPageURI(PageIndex: Integer): String;
begin
 if PageIndex = -1 then                      //URI of the index requested?
  Result := 'User_Index'                       //return its name
 else
  begin
   Assert((PageIndex >= 0) and (PageIndex < FUserComments.PageCount));
   Result := Format('User_%d', [PageIndex]);   //return name of the page
  end;
end;

{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 TICCommentDoc.GetGUIHelpURIByIndex(FileIndex,
                                            TopicIndex: Integer): String;
var      Data         :TICGUIHelpData;          //the data of the file
begin
 Data := FGUIHelpData[FileIndex];               //get data of the file

 //get URI of the documentation of the file
 Result := 'G_' + Data.BaseName;
 if TopicIndex <> -1 then                       //URI of topic searched?
  if TopicIndex = -2 then                         //is default topic?
   Result := Result + '..' + GUIHelpTopicSpecialPrefix + 'Default'  //use it
  else
   Result := Result + '..' + Data.Comments[TopicIndex].Name; //append topic
end;






















{Returns whether raw line breaks should be preserved within the comment.
~result whether raw line breaks should be preserved }
function TICCommentDoc.GetKeepRawLineBreaks: Boolean;
begin
 Result := FKeepLineBreaksInComments and        //should be preserved?
           //in a comment inside the source code?
           (Assigned(FCommentIdent) or Assigned(FCommentFile));
end;