#4 Inherited comments, @implements tag

[Michalis Kamburelis]

This is a patch from Ilya Illarionov, that (for various reasons...) was lying unapplied on Michalis disk. I'm submitting it here, so it will get applied (or at least decided about) eventually --- probably after merging some DoDi work, to stabilize a little.

Below I'm pasting the relevant comments about the patch from Ilya Illarionov.

---

1. FEATURE: INHERITED COMMENTS (Common core. Output implemented in HtmlDoc
   only.) Some Pascal items (classes, virtual overridden class methods, class
   properties, overloaded routines and class methods) can inherit absent
   comment parts (parameters, abstracts, descriptions etc.) from their
   ancestors automatically. Using inherited comments author doesn't have to
   specify comments for each inherited item in class, just declarations. Such
   approach facilitates a writing of inherited elements, at the same time
   provides full documentation generated by PasDoc for inherited items.

For example:
{ @abstract Basic class
Basic description }
TBasic = class
{ @abstract Method to perform something
Method description
@param Param Some param }
procedure BasicMethod(Param : Type); virtual; end;

{ @abstract Inherited class }
TInherited = class(TBasic)
procedure BasicMethod(Param : Type); override; end;

In spite of absent comments for TInherited class, PasDoc will fully document
TInherited.BasicMethod, using comments from ancestor. For TInherited class
itself PasDoc will use abstract "Inherited class" but description (since its
own description is empty) "Basic Description".

1. FEATURE: @IMPLEMENTS keyword. Comments inheritance mechanism for
   INHERITED COMMENTS. Using specified ancestor instead of automatic ancestor
   search. Very useful for documenting class member that implements behaviours
   for interfaces (eventually implemented by class) or other objects that are
   related to such a member.

For example:
MyInterface = interface(IInterface)
{ @abstract Does something
Some description
@param Param Necessary parameter }
procedure InterfaceMethod(Param : OleVariant); end;

{ @abstract MyInterface implementation } MyClass = class(TInterfacedObject,
IInterface)
{ @implements MyInterface.InterfaceMethod }
procedure InterfaceMethod(Param : OleVariant); end;

Author does not need to copy comments from interface method to its
implementation, he just have to mark class method as an implementation of
interface method.

Next example:

TNestedClass = class;

TBoundaryClass = class
private
FNested : TNestedClass;
public
{ @abstract Some Action
@param Param Some param }
procedure PerformBoundaryAction (Param : Variant); end; .....
procedure TBoundaryClass.PerformBoundaryAction (Param : Variant); begin
if Assigned(FNested) then FNested.PerformMyAction(Param); end;

TNestedClass=class
public
{ @implements TBoundaryClass.PerformBoundaryAction }
procedure PerformMyAction(Param : Variant); virtual; abstract; end;

Author does not need to copy comments from owning class method to nested
class method (and vice versa), but he points the fact that nested class
method have to be called from boundary class as dynamic behaviour
implementation.

1. Some win-1251, KOI8-R, cp866 translation was done.

2. FEATURE: "All members", "All fields", "All methods", "All properties"
   (including inherited) links added to CIO documentation page (for HTML output
   only).

3. ADDON: DPRUNITLIST unitily is implemented (source code available with
   free third party regexp library). This console utility outputs to STDOUT
   (using absolute or relative path) units being directly included into Delphi
   Project.

4. FEATURE: @param, @returns, @raises keywords are added to class
   properties. Reading property via PropGet method can raises an exception,
   doesn't it? And array properties can have one or more parameters.

---

Please, remove any ILLARIONOV signatures from source files before you will
publish them. You may refer to me (if you want) in some unit headers. My
name is Ilya Illarionov, and actual e-mail is <billythekidd AT="" mail="" DOT="" ru="">.

[Michalis Kamburelis]