[fpc-devel] MakeSkel and FPDoc projects

[Michael Van Canneyt]

On Fri, 16 Dec 2011, Hans-Peter Diettrich wrote:

> When MakeSkel shall use FPDoc projects, this can be achieved by adding 
> something like:
>
> procedure LoadProject(const Arg: string);
> begin
>  ProjectName := Arg;
>  Project := TFPDocProject.Create(Nil); //owner component?
>  With TXMLFPDocOptions.Create(Project) do
>    try
>      LoadOptionsFromFile(Project,Arg);
>      if (PackageName = '') and (Project.Packages.Count > 0) then
>        PackageName := Project.Packages[0].Name;
>    finally
>      Free;
>    end;
> end;
>
> Handling of the InputFiles and DescrFiles can be added similar to above 
> handling of the (default) PackageName, e.g.
>
>      if assigned(Project) then
>      //the package *must* be part of the project
>        Pkg := Project.Packages.FindPackage(PackageName)
>      else
>        Pkg := nil; //project not usable
>      if assigned(Pkg) then begin
>        InputFiles.Assign(Pkg.Inputs);
>        DescrFiles.Assign(Pkg.Descriptions);
>        //extract further options?
>      end;
>      DocumentPackage(...)
>
> Since new description files should be added to the project, I'd suggest that 
> MakeSkel uses a Project and the lists as stored in it, instead of the 
> InputFiles and DescrFiles variables. This change only affects the program 
> code, which passes these lists to DocumentPackage.
>
> 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.

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


> 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.
Given that, I don't see how you can avoid scanning for a project first.

Michael.