[Lazarus] Duplicate items in xml doc files

[Michael Van Canneyt]

On Tue, 17 Dec 2019, Werner Pamler via lazarus wrote:

> Fixing a docs-related issue today 
> (https://bugs.freepascal.org/view.php?id=36452), I noticed that the entry for 
> TCanvas.PolyBezier almost does not have any elements when the item is 
> displayed in the *FPDoc editor* of Lazarus, i.e. I do "View" > "FPDoc Editor" 
> and place the cursor in the normal source code window on the PolyBezier 
> identifier - then the FPDoc editor displays only the "short" text, all other 
> tabs are empty. On the other hand, the full chm file contains a lot more 
> information 
> (https://lazarus-ccr.sourceforge.io/docs/lcl/graphics/tcanvas.polybezier.html), 
> among it the description node which is the topic of that bug report.
>
> How is this possible?

It's XML, not a database with a unique index on element name.
There is nothing to stop you from adding an entry twice, but such a feature
could easily be added to the editors...

> On the other hand, opening the file graphics.xml in the *LazDocEditor *and 
> finding the TCanvas node shows two PolyBezier nodes. The first one contains 
> the text from the chm file, the second one has subnodes for the parameters of 
> the function - there is no text assigned to them, but some of them are listed 
> twice.
>
> There are other help items which show the same phenomenon: Chord, Polygon, 
> PolyLine, RadialPie, where Polygon even has three entries!
>
> Is this correct? If yes it is at least very confusing and makes the 
> LazDocEditor possibly a dangerous tool because the xml file might be damaged 
> when text is added to the wrong node.

Why would that damage the XML ?

> Can both tools, FPDoc Editor and LazDocEditor, be used to edit help 
> information? Or is it recommended to do this manually (which is extremely 
> error-prone)?

For FPC, I only edit manually. I don't see why this would be error prone ?

> And why are there so many empty lines? If they were added by either 
> FPDocEditor or LazDocEditor (and not by the author manually) then these tools 
> do not look very mature.

The empty lines are irrelevant.

> Probably related: the source code mouse-over hint of PolyBezier shows only 
> the "short" text, not the full "description".

That will depend on the XML node that is chosen to display the help.

Michael.