On Fri, 2 Dec 2011, Sven Barth wrote:
On 02.12.2011 19:37, Michael Van Canneyt wrote:
On Fri, 2 Dec 2011, Sven Barth wrote:
Am 02.12.2011 17:21, schrieb Michael Van Canneyt:
This means that we can document platform-specific items in additional
files, which are automatically merged with the other descriptions. The
description file specifications can be extended by a platform
attribute, so that problems arising from multiple (platform specific)
descriptions can be eliminated. E.g.:
<description file="sysutils.xml"/>
<description file="linux-sysutils.xml" platform="linux,unix"/>
<description file="win-sysutils.xml" platform=windows/>
I don't see the point of this. Why not simply add them to the
description file sysutils.xml ?
<element> tags for which no source file identifier exists are discarded
anyway.
If anything needs to be done at all, I see more use in adding a
'platform' tag to the element tags themselves; That would give the
documentation generator useful information which it can use. In fact,
the 'platform' directive should in the first place be in the sources
themselves, where it will be picked up by the scanner/parser - as per
the remark of Marco.
Out of curiosity: How could/would one create one documentation of
source which supports multiple platforms, but where there are
identifiers that are only available for some platforms? (like our RTL)
You currently can't as long as the source files are different.
And even with the same source file it is difficult, since the parser
will always parse only one branch from an IFDEF.
{$IFDEF WINDOWS}
THANDLE = Handle;
{$ELSE}
THANDLE = Pointer;
{$endif}
Cannot be parsed correctly. Same for library units with different
calling conventions etc.
Somehow that's what I feared based on your explanation above (Note: I don't
have the need for it currently, but I believe it's a "nice to have")
One workaround is to do something like is currently done in the RTL.
Let fpdoc define a conditional (e.g. FPDOCSYSTEM) and add dummy identifiers to the unit:
{$IFDEF FPDOCSYSTEM}
// Add definitions for fpdoc here which are normally not present.
{$ENDIF}
This way, they are documented, but not in the actual unit.
(unless someone actually wants to cheat the compiler and compile the unit with
-dFPDOCSYSTEM)
Michael.
_______________________________________________
fpc-devel maillist - fpc-devel@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-devel
