[PATCH 3/9] doc: preserve links produced by Doxygen

[Pekka Paalanen]

On Tue, 25 Nov 2014 09:44:02 -0800
Bill Spitzak <spitzak at gmail.com> wrote:

> On 11/25/2014 06:46 AM, Pekka Paalanen wrote:
> > On Tue, 11 Nov 2014 18:42:56 -0800
> > Bill Spitzak <spitzak at gmail.com> wrote:
> >
> >> These links are pretty useful for navigation, though sometimes excessive
> >> (you can turn them off by putting % before the word in the comment).
> >>
> >> I had to turn off validation because it failed on missing and duplicate
> >> target id's, which this produces.
> >
> > Yeah, very useful. Do we have a plan how to get validation back and
> > working? I assume it's not useless.
> 
> Is there any way to make it ignore links to missing and duplicate 
> targets but validate everything else?
> 
> Also I suppose a much more complex xslt script would do this by actually 
> building data structures and producing only the used tags.
> 
> My knowledge of xslt consists of asking questions on google and looking 
> at the existing xslt scripts.
> 

I'd be interested in hearing how we end up with
a) missing targets, and b) duplicate targets.

Could missing targets be fixed by documenting things that are not yet
documented? If yes, that would probably be nice.

If we ever get duplicate targets, then obviously some links point to
wrong things, because they cannot differentiate between the two
different targets of the same id. Is there something we could do in the
actual documentation to fix these? E.g. do we accidentally have two
different documentation blocks for a same thing, and merging them
would fix it?

Or are duplicates perhaps due to us having, say, struct wl_display a
different thing on server vs. client?

I'm adding Jon to CC, since he seems interested in things XML and docs.


Thanks,
pq