ucommentscanner.pas

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

~param Desc  out: the description of the option (name, type, default value,
                  etc.) }
procedure TCommentScannerOptionWrapper.Description(Index: Cardinal;
                                                 var Desc: TOptionDescription);
begin //get description from scanner
 FCommentScanner.GetOptionDescription(Index, Desc);
end;


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


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

 //get the parent class of the scanner introducing the option
 AClass := TCommentScannerClass(FCommentScanner.ClassType);
 while (AClass <> TCommentScanner) and
       (TCommentScannerClass(AClass.ClassParent).GetOptionCount > Index) do
  AClass := TCommentScannerClass(AClass.ClassParent);

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

















   { * *  ***  *  ***   TCommentScanner   ***  *  ***  * *  }



{Creates the object to scan comments and transform them to the
 ~[linkUnit UICNodes COM].
~param Generator the generator for which the comments should be read and
                 transformed }
constructor TCommentScanner.Create(Generator: TICDocumentDoc);
begin
 inherited Create;                       //create the object

 FGenerator := Generator;                //save the reference

 FGUIScreenShotExtension := '.bmp';      //initialize options
end;

{Frees the object and the accessor of options. }
destructor TCommentScanner.Destroy;
begin
 FOptionAccessor.Free;                   //free object to access the options

 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 TCommentScanner.GetOptionCount: Cardinal;
begin
 Result := 1;                         //one option in this class
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.)
~see GetOptionCount }
class procedure TCommentScanner.GetOptionDescription(Index: Cardinal;
                                                 var Desc: TOptionDescription);
begin
 ClearDescription(Desc);                 //clear structure
 case Index of                           //depending on index of option
   0:  begin                             //set the values describing the option
        Desc.Name := 'GUIScreenShotExtension';
        Desc.Category := 'GUIHelp';
        Desc.Description := 'The file extension of the screenshots of GUIs which are documented as a help for them.';
        Desc.DataType := otString;
        Desc.DefaultValue.StrData := '.bmp';
       end;
 else
  Assert(Index >= GetOptionCount);       //invalid index!
  raise EInvalidOption.Create('Invalid index for option supplied!');
 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 TCommentScanner.GetOption(Index: Cardinal): TOptionValue;
begin
 case Index of                         //depending on index of option
   0: Result.StrData := FGUIScreenShotExtension; //get the value
 else
  Assert(Index >= GetOptionCount);     //invalid index!
  raise EInvalidOption.Create('Invalid index for option supplied!');
 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 TCommentScanner.SetOption(Index: Cardinal; Value: TOptionValue);
begin
 case Index of                         //depending on index of option
   0: FGUIScreenShotExtension := Value.StrData;  //set the value
 else
  Assert(Index >= GetOptionCount);     //invalid index!
  raise EInvalidOption.Create('Invalid index for option supplied!');
 end;
end;


{Returns an object to edit the options of the scanner of the comments.
 The object must not be freed.
~result an object to edit the options of the scanner of comments }
function TCommentScanner.GetOptions: TOptionWrapper;
begin
 if not Assigned(FOptionAccessor) then          //accessor does not exist yet?
  FOptionAccessor := TCommentScannerOptionWrapper.Create(Self);   //create it
 Result := FOptionAccessor;                     //return the wrapper
end;



{Resets the attributes to ready the scanner for a new generation. }
procedure TCommentScanner.ResetForNewGeneration;
begin
 //reset call back to get the current position
 FOnGetPosition := nil;
end;





























{Add a scanner to the list of scanners.
~param CommentScannerClass the scanner of comments to add to the list }
procedure AddCommentScannerClass(CommentScannerClass: TCommentScannerClass);
begin
 if not assigned(CommentScannerClasses) then    //list not initialized, yet?
  CommentScannerClasses := TStringList.Create;    //create it

 //add the scanner with its name
 CommentScannerClasses.AddObject(CommentScannerClass.ClassName,
                                 TObject(CommentScannerClass));
end;

{Returns the default scanner of comments to be used.
~result the class of the default scanner }
function DefaultScannerClass: TCommentScannerClass;
begin
 Result := TCommentScannerClass(CommentScannerClasses.Objects[0]);
end;


initialization
 //create list of comments scanners unless already created
 if not Assigned(CommentScannerClasses) then
  CommentScannerClasses := TStringList.Create;

finalization
 CommentScannerClasses.Free;                    //free the list of scanners

end.