Michael Van Canneyt schrieb:
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 ?
You're right. So what's the use of --ostarget and --cpuversion, WRT
common documentation?
<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.
Right.
It may make sense to place the platform specific files into dedicated
subdirectories. When fpdoc is extended with description directories,
from which all XML files are collected automatically, it will be
sufficient to provide the platform-specific directories to fpdoc, so
that most explicit --descr items can be removed or replaced by:
<description file="*.xml"/>
<description file="windows/*.xml"/>
or
<description directory="windows"/>
I have no plans to support directory or wildcard search in fpdoc. That
is a can of worms I will not open;
I just implemented wildcards, and it seems to work nicely :-)
One objection is for instance that your proposal will cause all XML
files to be loaded both when FCL and RTL documentation are created.
Already included: all XML files are discarded, when they don't
contribute to the current package :-)
In general: "Keep it simple" is a good design strategy.
All these 'automatisms' should be delegated to separate tools. This
keeps things simple, much more maintainable.
Well, I found it the simplest approach to add certain features to fpdoc
itself, as long as nothing else is broken.
Your strategy seems to be to put everything and the kitchen sink in fpdoc.
You would be far better off making separate tools that implement these
automatisms. You can write a e.g. tool that creates or updates a project
file based on a directory scan.
There may remain things, which better should (and can!) reside in
separate tools. Currently I feel no need for such additional tools,
where the purpose would justify such efforts.
I have no problem including such tools in the FPC distribution, whereas
wildcard search in fpdoc itself is sure to be rejected.
I already expected such a reaction ;-)
As long as the the fpdoc classes cannot be used and extended outside
fpdoc, I see no way around inofficial patches, for private use. The
number of fpdoc users is very limited, most users will be comfortable
with the final documenatation, so that there exists no urgent need to
improve the distributed fpdoc itself. Fortunately my work on fpdoc
itself is almost finished, so that I can return to the Lazarus
documentation now.
DoDi
_______________________________________________
fpc-devel maillist - fpc-devel@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-devel
