[fpc-devel] MakeSkel and FPDoc projects

[Hans-Peter Diettrich]

Michael Van Canneyt schrieb:

>> Then the created skeletons can be added to the DescrFiles list, and 
>> the updated project can be saved on exit.
> 
> I don't think this is good. makeskel creates a diff, you should not add 
> this to the list of files; instead, after it was created, it should be 
> merged with the original file.

Plase keep --update mode (what you mean) distinct from normal mode 
(create new skeleton).



>> Furthermore it should be possible to process a single module from a 
>> project package, for which e.g. a skeleton shall be created, or which 
>> should be checked for errors by fpdoc. This requires that the --input 
>> value selects one of the input files in the project. This can be 
>> simplified by splitting the InputFile strings, into File and Options 
>> parts, as is already done in the project files. The stringlist 
>> representation could e.g. look like <file>=<options>, so that 
>> IndexOfName can be used to select an entry, and the "=" is replaced by 
>> an space before the entry is passed to the worker code. Then also 
>> another option --unit=<unit-name> can be used to select the specific 
>> input file to process. Then the stringlist representation also can be 
>> changed to <unit-name>=<existing --input descriptor>, and 
>> Values[<unit-name>] can be passed to the worker code.
> 
> No. You forget that the coupling with unit names does not exist.

Please explain?

Both FPDoc and MakeSkel accept one or more --input arguments, each 
representing one *unit*. When a project is used instead, either none or 
all units can be selected automatically, but not a single one.

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?


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

> 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 :-(

Did you ever try to *work* with FPDoc projects?

DoDi