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.
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.
5) FPDoc editor formatting buttons do not work in "See also" tab -- they should either work or be disabled.
6) Undo works very strange. This is probably generic LCL/TMemo issue, but one part is definitely FPDoc-specific: undo ignores changes made by pressing formatting buttons.
7) Changes made on "See also" tab do not activate "Save" button.
8) Adding documentation paths to "FPDoc editor files" option should be automated somehow --
right now the user who just install Lazarus and uses TAChart will _not_ see any documentation
until he adds the path manually.
9) "Insert a link" formatting button tries to present some list of "Link targets".
Unfortunately, this list containg only top-level targets like "LCL" and "RTL", while most links point to concrete classes and procedures. So some kind of treeview of link targets would be much more useful.
10) Link target list lacks scrollbar(s).
11) "Insert a link" dialog sometimes hangs Lazarus. I believe the following stack trace is relevant to hanging, but I did not investigate further:

TFPDocEditor.LoadGUIValues Short="The mode of reticule drawing"TApplication.HandleException Access violation Stack trace:
$0040E75B
$0097D8E3 TFPDOCLINKEDITORDLG__ADDSUBIDENTIFIERS, line 477 of fpdocselectlink.pas
$0097CF2F TFPDOCLINKEDITORDLG__UPDATECOMPLETIONBOX, line 334 of fpdocselectlink.pas
$0097DCC7 TFPDOCLINKEDITORDLG__SETLINK, line 545 of fpdocselectlink.pas $0097CAFC TFPDOCLINKEDITORDLG__COMPLETIONBOXMOUSEDOWN, line 233 of fpdocselectlink.pas
$00521172 TCONTROL__MOUSEDOWN, line 3599 of ./include/control.inc $0051D764 TCONTROL__DOMOUSEDOWN, line 1678 of ./include/control.inc $0051DBAD TCONTROL__WMLBUTTONDOWN, line 1817 of ./include/control.inc $0040B5DE
$0051C518 TCONTROL__PERFORM, line 1027 of ./include/control.inc $00513F17 TWINCONTROL__ISCONTROLMOUSEMSG, line 4498 of ./include/wincontrol.inc
$0051501E TWINCONTROL__WNDPROC, line 5050 of ./include/wincontrol.inc $0041883F TCUSTOMFORM__WNDPROC, line 1086 of ./include/customform.inc $0059E017 DELIVERMESSAGE, line 111 of lclmessageglue.pas $0053CFC3 WINDOWPROC, line 2617 of win32callback.inc

12) There seems to be no way to create lists in documention.

2009/10/9 Alexander Klenin :

Yeah, makeskel is only useful if you use the external 'lazde' or 'fpde' tools. The internal FPDoc Editor doesn't need skeleton xml files any more.

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"

+1

4) Help files generated by FPDoc utility miss description of enumeration constants.

I believe method parameters are also an issue.

10) Link target list lacks scrollbar(s).

I also battled with the "insert link" feature. That's where the external 'lazde' is still much better. In the end I typed the links manually, only because I knew the syntax. But this is an issue.

12) There seems to be no way to create lists in documention.

Again, something that 'lazde' is better at.

Overall, I think the whole idea of having to enter raw syntax should be removed. What we need is a WYSIWYG editor, so it can hide the complexities of the fpdoc syntax. That would mean any help author can add documentation and not have no worry about learning fpdoc syntax first, or manually edit xml files for certain features. Yes I know this will be great, but time consuming to implement.

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.

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.

2009/10/9 Graeme Geldenhuys :

> 4) Help files generated by FPDoc utility miss description of > enumeration constants. I believe method parameters are also an issue.

I meant to say the FPDoc editor is unable to allow editing descriptions of such items. At least that was true, last time I tried. I'll double check this again with the latest Lazarus just to be sure.

Regards,
- Graeme -

_______________________________________________
fpGUI - a cross-platform Free Pascal GUI toolkit
http://opensoft.homeip.net/fpgui/

Yes, this is what I meant.

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.

If so, then there are two bugs here:
1) FPDoc should issue an error upon encountering <descr> field for enumeration constant.
2) FPDoc editor should not allow entering it.

Well, a warning, at best... It's not an error.

Also, nothing stops people from enhancing the output engines so they take the descr tag into consideration.

Michael.

Alexander Klenin wrote

8) Adding documentation paths to "FPDoc editor files" option should be automated somehow --?right now the user who just install Lazarus and uses TAChart will _not_ see any documentation?until he adds the path manually.

Ah, I found LazDoc path package attribute, so this is already done, although not very documented.

Ok, I agree.

2009/10/9 Alexander Klenin :

> _not_ see any documentation?until he adds the path manually. Ah, I found LazDoc path package attribute, so this is already done, although not very documented.

Yeah, it would be nice if the IDE had it's own application help with Indexes and good Search support. ;-)

A few more bugs -- these IMO should go to directly to Mantis, but it does not respond for me at the moment.

1) "Create new item" button on FPDoc editor automatically adds the path to docs into LAzDoc path property of current package -- this is very good.
However:
1a) It adds absolute path, while using either package-relative or LazarusDir-relative would make more sense.
1b) If I fix the path manually my using $(LazarusDir) macro, "Create new item" button stops working.

2) On Windows, when saving document with manually entered line breaks, editor replaces them with LF
characters, instead of correct (for this platform) CR-LF sequence. This results in mixed line-endings file.

In the past the xml units of fpc required #10 as line ending.

Vincent

Fixed.

1b) If I fix the path manually my using $(LazarusDir) macro, "Create new item" button stops working.

Fixed.

2) On Windows, when saving document with manually entered line breaks, editor replaces them with LF characters, instead of correct (for this platform) CR-LF sequence. This results in mixed line-endings file.

Fixed.

Mattias

Thanks.

Unfortunately, things became worse now --
editor eats the first character on every line after the first one.

I fixed a bug wit windows line endings, but I don't have a windows here to test. Can you try again?

Mattias

Yes, this in an improvement, no more char eating.
It still inserts and removed line breaks seemingly at random, but at least they are proper line breaks ;-)

Also, not directly related bug:
1) Open components/tachart/TACustomSeries unit
2) Hover mouse over TChartSeries.Add function name in implementation section (line 196)
=> Hint is duplicated in the tooltip
3) Hover mouse over TChartSeries.AddXY name below
=> Hint is triplicated

And possibly related one:
1) Open FPDoc editor, put cursor on TChartSeries.Add function name, open Description tab in editor.
2) Put cursor at the end f the second line, after "</p>"
3) Press Enter
4) Press "Save" button
=> Lazarus crashes with the message: <Stream>(8, 9) error: Expected "="

Fixed.

No such error here.
But there is no xml check in the editor yet and therefore any syntax error raises an exception. It now catches EXMLReadError exceptions. Probably a synedit would be better than a memo. It can highlight corresponding fpdoc tags and errors.

Mattias

Mattias Gaertner wrote

No such error here. But there is no xml check in the editor yet and therefore any syntax error raises an exception. It now catches EXMLReadError exceptions.

Does this mean that http://bugs.freepascal.org/view.php?id=13240 has been fixed?

Vincent

Zitat von Vincent Snijders :

Yes.

Mattias

Thanks.

Well, the catch kind-of-works --
it now says the same error in "FPDoc syntax error" message box ;-)