[fpc-devel] FPDoc improvements

[Hans-Peter Diettrich]

michael.vancanneyt at 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