[fpc-devel] FPDoc sources

[Hans-Peter Diettrich]

Graeme Geldenhuys schrieb:
> On 30/08/2011, Hans-Peter Diettrich  wrote:
>> Unfortunately fpdoc ignores all given xml files, when no corresponding
>> source file is given at the same time.
[...]
> You are more than welcome to extend the tool if you want. I (and
> probably many others) would also welcome an alternative to Makefile
> usage for building fpc's docs. I loathe Makefiles.

At least in theory the Makefile can be replaced by fpdoc project(s). It 
would be a nice feature when fpdoc could also *create* an project file, 
from a given commandline. This would allow to run Make once, and to use 
the created project(s) afterwards, on any platform.

For now I only want to remove the code that skips xml files without 
according source files. In the next step the --descr option should allow 
for a directory, from which all files can be picked automatically.


>> FCL have such irregular requirements, that much work is required to
>> provide a usable command line for the compilation of the according
>> documentation.
> 
> Lazarus IDE already contains all that information, so it's just a
> matter of extracting the paths and writing the fpdoc command line
> options to a batch file.

This was my idea as well, but I doubt that the Lazarus packages (lpk) 
contain all information, required to make fpdoc happy. The fcl.lpk 
contains only a few files, a fraction of the contained units and 
existing xml files. An rtl.lpk seems not to exist at all :-(


>> The Lazarus IDE already includes the FPDoc Editor, which allows to
>> document every identifier in the sources :-)
> 
> I wasn't referring to editing documentation, but rather "managing a
> documentation project". Just like you use an IDE to manage a source
> code project, so too one could use a tool to manage a fpdoc
> documentation project.

Currently it looks easier to edit an project file manually. Therefore my 
idea to let fpdoc create a project, in addition or instead of creating 
the documentation.


> In fact, I remember seeing something like that already. A quick search
> shows that fpde (included with FPC, but for GTK1 only), and Lazarus's
> lazde tool have this functionality already. See the Build dialog. You
> can specify the output format, source and include directories, some
> fpdoc parameters etc..  You can load and save a documentation project.
> I have no idea if it is fully implemented, but would imagine it is a
> bit outdated compared to fpdoc features. I can't compile either fpde
> or lazde projects at the moment. Maybe you have better luck.

I already extended LazDE, for tracking changes to the xml files, so that 
e.g. translators can know what has changed in the English documentation. 
But its internal structure is based on single files, no chance to open a 
package or the like. No idea of fpde, it seems to be not very different 
from LazDE, and I couldn't yet make it run on Windows.

DoDi