[fpc-devel] FPDoc improvements

[Hans-Peter Diettrich]

michael.vancanneyt at wisa.be schrieb:
> 
> 
> On Mon, 28 Nov 2011, Hans-Peter Diettrich wrote:
> 
>> I just implemented and option to create an XML project from the 
>> commandline arguments. This should allow to create projects from the 
>> scripts and Makefiles, used to build the documentation for the 
>> standard libraries. See Mantis #20769.
> 
> I had a look, I will apply the patch when I find a free moment.
> 
> 2 small remarks:
> 
> 1. When coding changes, please try to observe the style used.

Well, I don't like your style as well :-(
I could stop myself before removing all those empty lines, that make it 
hard to review your code...

> 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?


I understand that you'll have problems with (my) patches, of course. If 
you have *practical* suggestions, I'll try to match your expectations 
better.

I could e.g. enclose the various topics by conditional compilation, but 
I'm not sure whether this will be really helpful.


>> Unfortunately there remain some problems, e.g. the FPC documentation 
>> cannot be created on Windows, what is one reason for the extended 
>> project option, but doesn't allow me to debug this feature with real 
>> life projects (RTL...).
> 
> Why not ?

See my parallel mail, I suspect general problems with long command lines 
on Windows.

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.

The missing include files problem is harder to solve, because the 
scripts have to create different compiler options for every platform. 
This leads me to the question, how "portable" the make and other scripts 
should be, so that their output can be used on multiple platforms.

Perhaps the following settings:

const
   DefOSTarget    = {$I %FPCTARGETOS%};
   DefCPUTarget   = {$I %FPCTARGETCPU%};

should be replaced by the (already existing) commandline options, e.g. 
--ostarget, so that the given include directoris match the expectations 
of the script writers, and parsing the source files does not fail with 
missing include files. Dunno whether that helps, I did not yet dig into 
these details.


What you could do right now: split the fpdoc program file, so that 
further programs can be created for specific tasks, like creating an 
fpdoc project instead of creating output. You can do this from the 
unpatched version, so that nothing will be broken by that update.

This would allow to move most of the changes into derived classes, where 
the affected methods can be introduced or overridden, instead of 
modifications to the original classes and methods. Then it would also be 
possible to use the fpdoc worker code in other applications, like LazDE 
or build_lcl_docs. In detail I want to implement a GUI for the creation 
and maintenance of fpdoc projects, that allows for comfortable project 
debugging.

DoDi