[fpc-devel] fpdoc path + system.uitypes problems.

[Michael Van Canneyt]

On Mon, 25 Dec 2023, Marco van de Voort via fpc-devel wrote:

>
> (forum thread: 
> https://forum.lazarus.freepascal.org/index.php/topic,65629.0.html)
>
> Don noticed that the system.uitypes lemma's in the CHM are empty, both 
> with 3.2.x as 3.3.x fpdoc.
>
> I checked the only html snapshot and it is the same: 
> https://www.freepascal.org/daily/doc/rtl/system.uitypes/index-5.html
>
> I can remember that I tried to debug this a while back, and that this is 
> a fundamental problem of fpdoc because it uses dots to separate the 
> parts of a lemma. (e.g. packagename.unitname.recordtype.fieldname).  
> Separating a path on dot then breaks the unit name. If unit name is 
> system.uitypes.somevariable, it tries to find symbol uitypes in system, 
> and then searches for a  field in somevariable  etc.

This obviously needs to be extended. dotted unit names didn't exist when
fpdoc was made.

>
> To fix this either we have to e.g. keep a list of packages and a list of 
> units and then try to disambiguate to only pick the longest match. That 
> maybe have risks that other corner cases be found or that the list of 
> units is not yet complete at any point when this system is inside 
> fpdoc.  This requires no changes to the .xmls

This is the road to take. It's similar to what the compiler does, after all.

>
> A more definitive choice is to change something about the notation and 
> somehow replace or escape dots within identifiers. like  
> rtl.#system.uitypes#.recordtype.fieldname  or like

The # notation is already taken to indicate a fully qualified name.

> rtl.system#uitypes.recordtype.fieldname or 
> rtl.system..uitypes.recordtype.fieldname. (exact characters to be used 
> T.b.d.    Only requires changes to the XML for dotted unit names.

and everything referring to it since any cross-reference would also need to be changed.

I will have a look this week, I have holidays so I have some time.

Michael.