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.
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
