[fpc-devel] FPDoc improvements

[michael.vancanneyt at wisa.be]

On Tue, 29 Nov 2011, Hans-Peter Diettrich wrote:

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

You could have done so, and the result would have been that your patch would
maybe not have been accepted.

Always try to mimick the style used in code you modify.
The FPC team sticks to this rule ourselves when we modify other people's code,
and we ask the same from you. (as you well know)

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

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

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.

Since there is no 1-1 relation, the description files must be enumerated.

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)

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

I cannot answer this question.

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

It won't, see above.

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

Since the project definition already is in a separate file, I fail to see what can
be moved more ? Please be more specific.

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.

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.

If there are things you don't understand, feel free to ask questions, and I
will answer them as best as I can.

Michael.