On Sat, 3 Dec 2011, Graeme Geldenhuys wrote:
On 3 December 2011 01:59, Michael Van Canneyt wrote:
Already included: all XML files are discarded, when they don't contribute
to the current package :-)
Because of the loose coupling between XML files and source files, there is
no way to know if a XML file is contributing or not, unless you impose some
convention like 1 unit = 1 file with equal filenames, or parse the XML file
to detect the module it documents or start moving XML files to directories.
I've always wonder about the very verbose command line parameters used
with fpdoc. Why couldn't the XML simply mention which unit(s) it
documents. You could also include macros [eg: $(somemacro) ] which
fpdoc could substitute when the xml file is processed. The macros
could be defined in some fpdoc.ini file, or passed as command line
option. I would opt for the ini file choice, but the command line
param could be used to override the macro if needed.
Strictly speaking, the XML file does say which units it documents.
See the <module name=xyz"> tag. One problem is that you know this
only after you have parsed the XML when you should know before starting.
I think there are several other reasons why the project file approach is more
powerful.
First, it keeps the actual documentation XML more "clean" in the sense that
it contains only documentation, and not 'organizational instructions'.
Just like a lazarus project file (.lpi) is different from the actual source
file (lpr).
You'll remember that Delphi used to try and put all project info in the
.dpr file, and I think we all know what a pain that was.
I think it would also require the documentation writer to foresee organizational
issues and parametrize them in the XML, which I think is something the documentation
writer should not have to care about. The person generating the documentation, on the
other hand, 'knows' the possible situations and can parametrize his project
file for this. (and indeed, can create many different project files)
Speed is also an option. If we start allowing macros, then as an end result
the macros must be processed in the whole XML file. The documentation XML
is rather big; the project file is small.
In true unix philosophy, I think it is better to have many small and simple
tools
cooperating well than one large tool which tries to do everything and fails
miserably. There you have, in a nutshell, the design philosophy of fpdoc :-)
Michael.
_______________________________________________
fpc-devel maillist - fpc-devel@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-devel
