Re: linkification warnings

[Nicola Fontana <ntd entidi it>]

Il giorno Sat, 19 Dec 2009 22:40:22 +0100
David Nečas <yeti physics muni cz> ha scritto:

> On Sat, Dec 19, 2009 at 10:49:41PM +0200, Stefan Kost wrote:
> > This is one of the flaws in the historic (non-)design. I have not
> > thought about it. My current thinking is to make
> > - #GtkWidget -> Section docs
> > - #GtkWidget-struct -> object instance struct docs
> > - #GtkWidget.member -> object instance struct-member docs
> > - ...
> > 
> > So in fixxref we could try to smuggle the "-struct" in when the
> > #GtkWidget.member link can otherwise not be resolved. How does that
> > sound?
> 
> Does it mean that if the member is called `signals' I have to write
> #GtkWidget-struct.signals but when it's called `foobar' I have to
> write #GtkWidget.foobar and when gtk-doc adds a generated section
> foobar I am in trouble?

This is the main problem: the ids generated from the C code share the
same namespace with the ids of the document structure. Silently
stripping the "-struct" suffix will breed (at least theoretically) id
clashes: `description' and `details' are also quite common field names.

My suggestion is to keep the situation as is. The proper solution would
be to isolate the two namespaces in some way, for example by prefixing
the document structure ids with something that cannot be present in a C
identifier. This will likely break every documentation with
hand-written links to sections, though.

Ciao.
-- 
Nicola