[fpc-devel] fpdoc has incomplete type definitions in the documentation output

[Michael Van Canneyt]

On Wed, 11 Aug 2010, Graeme Geldenhuys wrote:

> Hi,
>
> When generating HTML class documentation, the Class definition displayed is
> not the same as the actual class definition in the code. The definition in
> the HTML docs show:
>
> type
>  TfpgBaseButton = class(TfpgWidget)
>
> when in fact the real code in the .pas unit is:
>
> type
>  TfpgBaseButton = class(TfpgWidget, ICommandHolder)
>
> I mentioned in a 'feature request' that it would be nice if the class
> documentation can list the implemented interfaces (something like JavaDoc
> does). That would be nice, but even if we can start by including the "real"
> class definition in the documentation output, that would be good too.
>
> I found more such problems (not relating to Interfaces too). For example, I
> have a record that is marked as 'deprecated' in the pas unit. But the HTML
> type definition of that record doesn't show the 'deprecated' keyword.
> eg: HTML output.
>
> type
> TRGBTriple = record
>  Red: Word;
>  Green: Word;
>  Blue: Word;
>  Alpha: Word;
> end;
>
>
> but the real code in the .pas unit is as follows:
>
>  TRGBTriple = record
>    Red: word;
>    Green: word;
>    Blue: word;
>    Alpha: word;
>  end deprecated;
>
> Note the HTML output is missing the 'deprecated' keyword. Same as the
> missing implemented Interface in my button example. Another example is a
> property with the 'platform' modifier. The definition shown in the fpdoc
> class documentation doesn't include the 'platform' modifier in the code
> example.
>
>
> Is all this by design, or simply an oversight/bug in the fpdoc program?

These are oversights/bugs.

Especially HTML is problematic, as it 'reconstructs' the whole definition
from the TPasElement to be able to highlight instead of using GetDeclaration. 
The linear writers use simply the TPasElement.GetDeclaration call.

Please enter bug reports for any problems that you find.

Michael.