michael.vancann...@wisa.be schrieb:
2. Try to separate things. You coded a change in package selection
handling, please don't mix this with the change for writing a package
file. It makes it more difficult to debug when bugs arise.
How can I create patches for different topics, when the whole
application only works after all required changes have been
implemented together?
Selection of the package should be separate from that IMHO, if not,
there is
an error in your logic.
In this case I'd search the error in the existing logic. Projects are a
recent extension to fpdoc, which has not even been tested thorougly.
That's why there are many places in the code, which deserve a
reconsideration of the current model and procedures.
This suggests to me to use 2 file lists, for the descriptions and
*also* for the input (source) files. But IMO the list of description
files could be dropped entirely, when fpdoc simply searches for an XML
file for every given source unit, in the current or a given
documentation directory. It's useless to enumerate the XML files, when
documentation is created only for the given input files.
Then you misunderstand how fpdoc reads files.
1. It's perfectly possible for a single XML file to contain
documentation for several units. Practically, it means 1 XMl file can
contain many
<package> and <module> nodes. That I decided to use 1 XML file per unit
is pure coincidence. Vice versa, the documentation for 1 unit can be
split over 2 XML files. fpdoc will merge them.
This IMO is not very practical, not supported e.g. by LazDE. In contrast
it were more practical to *split* documentation, so that e.g. large
classes can be documented in their own file. I never tested whether
fpdoc could deal with such files as well...
Since there is no 1-1 relation, the description files must be enumerated.
In either case an enumeration of the XML files in the documentation
directories would be sufficient. Fpdoc already ignores all
documentation, for which no source files are given. When memory usage is
of concern, the excess modules can be deleted in the DOM tree.
2. The input file can contain a limited number of compiler options
'-DSomething'. Therefor, it cannot be used to determine the filename
(unless you start parsing it)
I'm not sure whether a description file is required *before* an input
file is being or has been parsed. It also looks somewhat expensive to
me, when *all* description files have to be loaded before the unit
specific documentation can be created, because fpdoc has to search *all*
description files for an matching module name.
IMO it were much more handy when the names of the description file(s)
would become an attribute of every input file, so that they can be
loaded on demand. When no such XML attribute exists, as is, a fallback
to the current search procedure can be used. For the current commandline
usage the description file could be added to the input specification,
perhaps as a new option -D<descr.xml>.
Currently, the fpdoc.pp source file only contains code which is useful
in a command-line enironment: it is a TCustomApplication class
descendant which
collects command-line arguments and passes them on to the objects that do
the actua work. It contains no other logic.
Consider the implementation of a stand-alone tool, that takes a
commandline and creates an fpdoc project from it - this is what I just
tried. When both the application class definition *and* its use reside
in the program file, its impossible to select a derived application
class, that performs an specific task or extends the functionality.
All code doing the actual work is in the other units, ready for re-use
by a GUI environment, or any other command-line tool you care to create.
This is not true - see what e.g. TFPDocApplication.CreateDocumentation does.
begin
With TFPDocAplication.Create(Nil) do
try
Run;
finally
Free;
end;
end.
When this were the *only* code in the fpdoc program file, another
project could create a derived class, with a possibly specialized Run
method, without touching the declaration or implementation of
TFPDocApplication.
DoDi
_______________________________________________
fpc-devel maillist - fpc-devel@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-devel
