[fpc-devel] MakeSkel and FPDoc projects

[Hans-Peter Diettrich]

Michael Van Canneyt schrieb:

>> Consider an existing FPDoc project, which contains all input files and 
>> all currently existing description files. When you want to create a 
>> new skeleton for an not yet documented unit, how to achieve that? 
>> Should the user copy the stored --input specification for that unit 
>> *manually*, including all compiler options? And should he afterwards 
>> add the new description file to the project, by editing the project 
>> file manually again?
> 
> Your problem is a false one.
> 
> I would never use a project file for this in the first place.

My argument for using projects is exactly that they contain the compiler 
options for all input files.

> You seem to assume that the project file *must* be used for makeskel. 
> For me this is still highly questionable. If it can be done, fine.
> If not: also fine.

ACK. There is no *need* to use MakeSkel with a project, but using this 
option offers many advantages.

When we look at new packages, some general tasks come into mind:

1) Generate a working FPDoc project, containing all input files and 
their related compiler options. Collecting all input files is not 
normally a problem, but many files may deserve special compiler options. 
How to proceed, in case of problems? Running fpdoc until all settings 
are okay may be a bad solution, you better update and try individual 
options for the units with problems.

2) Add documentation. I'd prefer an option that creates skeletons for 
all units, others may prefer to create skeletons only for specific 
units, which then are documented one-by-one. In either case the 
description files should be added to the project automatically.

3) Check for updates. Here it depends on the amount of changes to the 
input files of a project (package), whether everything should go into an 
common update file, or into multiple files. Eventually the source 
directories should be scanned for moved or added input files, which 
should become part of the project as well.

4) Check documentation updates for syntax errors and bad links. Again a 
first run should reveal all errors, in all files, while fixing the 
errors will require multiple runs over the same input files.

5) Check documentation for completeness. A list of all not yet 
documented items should be generated, so that the user knows where the 
documentation should be completed.

6) Create final documentation. This is the typical use case for fpdoc, 
but now only one very specific case in the entire process of providing 
documentation.

I'd prefer that all beforementioned tasks can be accomplished by a 
single program, by only giving it an project file, task, and 
task-specific options.


>>>> Currently FPDoc scans the commandline for a project first, before 
>>>> parsing the other options. This extra handling could be removed, 
>>>> with the effect that options before the --project option are 
>>>> defaults, which are overridden by the project settings, while 
>>>> options after --project override the project settings. This 
>>>> consideration applies to all programs, which accept an fpdoc project.
>>>
>>> Well, I don't like the fact that order of command-line options is 
>>> important.
>>
>> Well, I showed an practical use case, where such an order is useful.
> 
> I must have missed that. How did you show this ?

Think about an project file first, what does it contain? Then think 
about which of the stored options may deserve an override, or which 
require overrides in specific use cases. Also keep in mind that project 
files may be distributed, and that the target environments may deserve 
certain modifications. When I use "make all", to create the full RTL/FCL 
documentation on Windows, the resulting commandline does not always 
reflect the intentions of the documentation writers (on Linux). It IMO 
is a bad idea to store the OS and CPU targets and the output format in 
an project file.


>>> Given that, I don't see how you can avoid scanning for a project first.
>>
>> This means that you disallow for e.g. scripts which provide built-in 
>> defaults, that *should* be overridden by values stored in the project :-(
> 
> Of course I disallow this. The working method is the opposite. The 
> project provides defaults, to be overridden on the command line.

This is how you have learned or expect it to work. My approach may be 
quite different from your habits. Consider what has to be done when 
input files are added - the required updates depend on the source 
(script, Makefile) that creates a commandline. Currently only two 
options exist, to replace the existing project file by a new one, based 
on the generated command line, or to search for differences between the 
commandline and the existing project file. An automatic update wipes out 
all previously added (compiler) options, a manual compare is error prone 
by nature :-(

DoDi