[Pasdoc-main] [pasdoc:patches] #4 Inherited comments, @implements tag

[Michalis K. <ka...@us...>]

Comments from inherited things are now used for classes and class members. Realistically, this is an old patch which will not apply anymore. If anything is missing from latest PasDoc, please submit PR to the latest code on GitHub: https://github.com/pasdoc/pasdoc/pulls


---

**[patches:#4] Inherited comments, @implements tag**

**Status:** open
**Group:** 
**Created:** Thu Jul 10, 2008 10:08 PM UTC by Michalis Kamburelis
**Last Updated:** Mon Jun 30, 2014 10:39 PM UTC
**Owner:** nobody


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.

----

4. 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".

5. 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.

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

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

8. 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.

9. 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>.



---

Sent from sourceforge.net because pas...@li... is subscribed to https://sourceforge.net/p/pasdoc/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/pasdoc/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.