[fpc-devel] MakeSkel and FPDoc projects
DrDiettrich1 at aol.com
Sat Dec 17 05:50:49 CET 2011
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
I'd prefer that all beforementioned tasks can be accomplished by a
single program, by only giving it an project file, task, and
>>>> 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
>> 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 :-(
More information about the fpc-devel