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