[fpc-devel] convert comment help to fpcdoc

[Michalis Kamburelis]

2011/7/17 Sven Barth <pascaldragon at googlemail.com>:
> On 17.07.2011 08:08, Felipe Monteiro de Carvalho wrote:
>>
>> Since we are talking about help stuff, (in another thread)
>>
>> Do we have any tool to convert documentation written in javadoc style
>> (those comments in the source code) to fpdoc xml? I like to write my
>> documentation as comments...
>
> I don't know of anything of the FPC community, but at work we extended
> PasDoc ( http://pasdoc.sipsolutions.net/ ) to write fpdoc compatible XML
> files which was rather easy to do as the already is a XML output available.
> I haven't published this extension though as it was only used internally and
> now we've completly switched to PasDoc.
>

I wanted to implement output to fpdoc XML from pasdoc some time ago
too (http://pasdoc.sipsolutions.net/MichalisKamburelis#Fpdoc_output).
This would allow one to write comments inside sources, and generate
final documentation by fpdoc. This isn't really difficult, but there's
always not enough time...

For the proponents of "docs should be outside sources", it should be
noted that in pasdoc, you can also put docs in separate files, by
using http://pasdoc.sipsolutions.net/ReadDescriptionFromFile . But,
admittedly, this does look ugly compared to nice fpdoc XML format.

As for whether it's better to put comments in sources or in separate
files, I really think this is a matter of preference... Sure, docs
make the unit interface much larger, but they also make it more
useful. And they encourage to update docs immediately together with
updating the API. The generated docs always contain a concise summary
of identifiers, if one wants it. I wrote some more comments about this
on http://pasdoc.sipsolutions.net/MichalisKamburelis#Should_documentation_be_placed_inside_units_interface.2C_or_in_separate_files_.3F
.

In short, I like having the both options --- fpdoc is best for docs in
separate files, pasdoc is best for docs inside source files. And
pasdoc is maintained (although not as actively as I'd like, volunteers
are welcome :)

Michalis