[Lazarus] A report on documentation editors

[Michael Van Canneyt]

On Fri, 9 Oct 2009, Alexander Klenin wrote:

> I tried to create documentation for TAChart package using tools supplied
> with Lazarus.
>
> First, I tried to use lazde tool.
> I immediately encountered severe problems, starting with
> http://bugs.freepascal.org/view.php?id=14767 and going on from there,
> so I quickly gave up.
> It appears that lazde in unused and unmaintained.
> Since built-in FPDoc editor provides mostly the same functionality,
> I think it would be reasonable to deprecate/remove lazde in favor of
> build-in editor.
>
> Second, I used built-in FPDoc editor. I have got much better results with it,
> It was very easy to create and edit the documentation.
> I like that the changes I make are immediately picked up by IDE
> and displayed in the tooltips.
> Here are some bugs/improvement suggestions, in no particular order:
> 1) It is good that tooltips are now left-aligned, but I think the left
> margin of at least 2 pixels
>  is required for readability. Right now the first line of tooltip
> merges with the tooltip border.
> 2) I tried to use makeskel utility, and it indeed created a skeleton
> file for me,
>  but I did not find this file is useful. FPDoc editor is quite
> capable to create xml tags as needed,
>  and I think a huge array of empty tags is just a waste of code.

It is not: it tells you exactly what must still be documented.
That's what it is meant for.

I edit the XML files directly, and then this file is quite handy, 
especially the update mode of the tool.

> 3) "View/FPDoc editor" menu item was quite clear to me, but a novice
> user may not
>  instantly understand what it does. I suggest to replace menu item
> caption (and window caption)
>  with "Documentation editor"
> 4) Help files generated by FPDoc utility miss description of
> enumeration constants.

No they don't ?

See e.g. http://www.freepascal.org/docs-html/rtl/classes/tfilerflag.html

If you mean the full <descr> tag, then: yes, it is unused.

But this is 'by design'. The idea is that you describe the various
enumerated values in depth in the description of the enumerated type itself.

Michael.