uguihelpreader.pas

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

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2002-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}


unit UGUIHelpReader;

{Contains the class to parse the data about a GUI to generate a help about,
 ~[link TJADDGUIHelpReader].
}

interface



uses Windows, Classes,
     UOptions,
     UGenerationMessages,
     UOldGUIHelpData, UComments, UCommentDoc;

type





   { * * *  ***  * * *  ***   TJADDGUIHelpReader   ***  * * *  ***  * * *  }


  {The messages that can be generated by the generators. This type contains all
   types of messages for all (so far known) generators. }
  TJADDGUIHelpReaderMessageKind = (
                                   //the log file of the GUI is invalid
                                   jghrmkLogFileInvalid,


                                   //a file with help on a GUI can't be read
                                   jghrmkCantReadFile,
                                   //a file with help on a GUI has already be
                                   //read
                                   jghrmkDoubleFiles,
                                   //the target of a manual link in the image
                                   //of the GUI was not found, it is assumed it
                                   //is an external link
                                   jghrmkInvalidManualExternalLink,
                                   //a component on the GUI was not documented
                                   jghrmkNotDocumented,
                                   //some components on the GUI don't have
                                   //their help context set
                                   jghrmkNoHelpContext,

                                   //invalid alias specified
                                   jghrmkInvalidAliasNames,
                                   //invalid manual link specified
                                   jghrmkInvalidManualLink,
                                   //already specified documentation has been
                                   //replaced/overridden
                                   jghrmkDocumentationReplaced,
                                   //unknown name of special documentation
                                   //specified
                                   jghrmkUnknownSpecialDocumentation,
                                   //no or an invalid name of a topic/of a
                                   //component specified for a topic
                                   jghrmkInvalidTopicName,
                                   //text outside of sections in included files
                                   jghrmkTextOutsideSection,
                                   //a file of documentation is invalid, i.e.
                                   //none specified or not found
                                   jghrmkDocumentationFileInvalid,
                                   //some documented topics have not been used
                                   jghrmkUnusedTopics,

                                   //no section/topic  heading for the
                                   //documentation of a component of a GUI
                                   //specified
                                   jghrmkNoTopicHeading
                                  );


  {Readers of the data about a GUI to generate a help about. The data has to
   be in the same format as generated by the form ~[code TFormGUIHelp] in the
   unit "~[code UFormHelp.pas]" accompanying the source code of
   ~[em DelphiDoc]. The documentation has to be in "~[code *.txt]" files with
   the same base name in the same format as the comments have to be for JADD in
   general. }
  TJADDGUIHelpReader = class(TGUIHelpReader)
  private
    //ID of the messages of this class
    FJADDGUIHelpMessagesID: TMessageID;

    //if the automatically created auto-aliases from labels to their
    FGUIHelpUseAutoAliases: Boolean;        //"FocusControl"s should be used

    //whether the name of the topic of a linked component should be used as
    //the alternative text for the link instead of the name of the component
    FGUIHelpUseTopicAsLinkText: Boolean;



    //Adds a message of this class to the list of messages.
    procedure AddMessage(Msg: TJADDGUIHelpReaderMessageKind;
                         const Text: String);
    //Adds a message to the list of messages.
    procedure AddGeneratorMessage(Messages: TMessageID; Msg: Integer;
                                  const Text: String);

    //Extracts the header from the documentation of a topic/component of a GUI.
    function GUIHelpExtractHeader(var Comment: String;
                                  const ErrorMsg: String): String;
    //Extracts the topics of all comments in the file.
    procedure ParseTopics(Data: TOldGUIHelpData);

    //Parses the sections with data of documentation to generate help on a GUI.
    procedure ParseGUISections(Data: TOldGUIHelpData; const FileName: String;
                               Comment: TComment);
    //Reads a file of documentation for the help on a GUI.
    function ReadGUIDocumentationFile(Data: TOldGUIHelpData;
                                      const FileName: String;
                                      ParsedFiles: TStringList): String;
    //Read the documentation for the help on a GUI.
    procedure ReadGUIDocumentation(Data: TOldGUIHelpData);



    //Checks if the name is an alias and returns the final name.
    function GUIHelpUnalias(PossibleAliasName: String;
                            Data: TOldGUIHelpData): String;


  public
    //Creates reader of the data of the GUI to generate documentation about.
    constructor Create(Generator: TCommentDoc); override;
    //Unregisters the messages and frees the object.
    destructor Destroy; override;


    //Returns a description of the reader of data about a GUI.
    class function GetDescription: TGUIHelpReaderDescription; override;


    //Returns the number of available options in readers of this class.
    class function GetOptionCount: Cardinal; override;
    //Gets a description of an option.
    class procedure GetOptionDescription(Index: Cardinal;
                                         var Desc: TOptionDescription);
                                                                       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;



    //Parses all log files to generate a help for a GUI.
    procedure ParseAllLogFiles(GUIHelpFileList: TStrings); override;

    //Generate the linked image of the current file of documentation on a GUI.
    function GenerateGUIHelpImage(Data: TOldGUIHelpData): String; override;
    //Checks if all documentation topic in the help for a GUI are used.
    procedure CheckGUIDocumentationTopicUsage; override;
  end;






implementation

uses SysUtils,
     UFilePaths,
     UPascalConsts,
     UDocumentationTexts, UFormatCommentDoc;







   { * * *  ***  * * *  ***   TJADDGUIHelpReader   ***  * * *  ***  * * *  }


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



{Creates reader of the data of the GUI to generate documentation about.
~param Generator the generator that will generate the help about the GUI }
constructor TJADDGUIHelpReader.Create(Generator: TCommentDoc);
begin
 inherited Create(Generator);            //create the object

 FGUIHelpUseAutoAliases := True;         //by default use the logged aliases
 FGUIHelpUseTopicAsLinkText := True;     //by default use names of topics

 //register messages of this class
 FJADDGUIHelpMessagesID := Generator.RegisterMessages(
                                               JADDGUIHelpMessageDescriptions);
end;


{Unregisters the messages and frees the object. }
destructor TJADDGUIHelpReader.Destroy;
begin
 if assigned(Generator) then
  //unregister messages of this class
  Generator.UnRegisterMessages(FJADDGUIHelpMessagesID);

 inherited Destroy;                      //free the object
end;






{Returns a description of the reader of data about a GUI.
~result a description of the reader of data about a GUI }
class function TJADDGUIHelpReader.GetDescription: TGUIHelpReaderDescription;
begin
 Result.Name := 'JADD - GUI Help - Reader';
 Result.Identification := 'JADD';
 Result.Description := 'Reads the data in the format as generated by the form TFormGUIHelp in unit UFormHelp in the source distribution of JADD - Just Another DelphiDoc.';
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 TJADDGUIHelpReader.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 2;
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 TJADDGUIHelpReader.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 := 'GUIHelpUseAutoAliases';
          Desc.Category := 'GUIHelp';
          Desc.Description := 'Whether the automatically generated aliases should be used when generating help for a GUI.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         end;
     1:  begin
          Desc.Name := 'GUIHelpUseTopicAsLinkText';
          Desc.Category := 'GUIHelp';
          Desc.Description := 'Whether the name of the topic of a linked component should be used as the alternative text for the link instead of the name of the component.';
          Desc.DataType := otBoolean;
          Desc.DefaultValue.BoolData := True;
         end;
   else
    assert(Index >= GetOptionCount);
    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 TJADDGUIHelpReader.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 := FGUIHelpUseAutoAliases;  //get the value
     1: Result.BoolData := FGUIHelpUseTopicAsLinkText;
   else
    assert(Index >= GetOptionCount);
    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 TJADDGUIHelpReader.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: FGUIHelpUseAutoAliases := Value.BoolData; //set the value
    1: FGUIHelpUseTopicAsLinkText := Value.BoolData;
  else
   assert(Index >= GetOptionCount);
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;





{Adds a message of this class to the list of messages.
~param Msg  the ID/kind of the message of this class
~param Text the text of the message }
procedure TJADDGUIHelpReader.AddMessage(Msg: TJADDGUIHelpReaderMessageKind;
                                        const Text: String);
begin
 Generator.AddPositionMessage(FJADDGUIHelpMessagesID, Ord(Msg), Text);
end;

{Adds a message to the list of messages.
~param Messages the ID of the messages it should be one of
~param Msg      the number of the message of that ID it is
~param Text     the text of the message }
procedure TJADDGUIHelpReader.AddGeneratorMessage(Messages: TMessageID;
                                                 Msg: Integer;
                                                 const Text: String);
begin