[fpc-pascal] Re: Documentation

[michael.vancanneyt at wisa.be]

On Tue, 18 Dec 2012, Reinier Olislagers wrote:

> On 18-12-2012 0:58, Graeme Geldenhuys wrote:
>> There are other issues with the FPDoc Editor dialog though. Off the top
>> of my head:
>
> As I think I said last year, there's also Laz DE/Lazarus Documentation
> Editor.
>
> As long as we're suggesting improvements, I'd like LazDE to
> 1. show a formatted view of the resulting fpdoc (i.e. use fpdoc
> processing to output as e.g. HTML and show that) so you have direct
> feedback on how your documentation looks.
> 2. use an XML syntax highlighter (synmemo?) (if it's not already there).
> Helps with those missing closing tags etc I suffer from
> 3. allow drag and drop from an identifier in a source code window to
> create a link automatically.
> 4. (from memory, haven't done this a while) make it easier to start
> documenting a new unit. Whenever I start, I have no idea what package
> name I should supply. Some automated suggestions might be nice.
>
> However, fpdoc documentation writing is a huge chore for me compared to
> writing in the wiki so I've decided it's more productive to get my
> documentation done on the wiki.

A wiki is never documentation. It's an explanation - at best.

Usually (not targeting anyone here) it is sloppy, incomplete, not maintained,
no verification of the up-to-dateness possible.

It's some quick and dirty text which you jot down if and when you feel like it.

Writing quality documentation IS a chore. There is no way around it.
That is why companies have tech writers employed for this job.

> I still have documentation for the zip unit lying around and I'm trying
> to get that in shape to submit it.
>
> Meanwhile I've updated the fpdoc code some with cosmetic changes/better
> warning messages:
> http://bugs.freepascal.org/view.php?id=23506
> ... so if anybody is interested ;)

I applied the patch, thank you !

Michael.