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

[Pekka Paalanen]

On Wed, 26 Nov 2014 00:38:20 -0800
"Jon A. Cruz" <jonc at osg.samsung.com> wrote:

> On 11/25/2014 11:52 PM, Pekka Paalanen wrote:
> > 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.
> 
> Definitely sounds like something I can track down and address (since I'm
> experienced with xslt, doxygen, etc). At the very least I should be able
> to spot the worst blockers.
> 
> One step might be to get anything that is truly undocumented replaced
> with doxygen todo tags so we get a build without warnings but can still
> get a list of items to fix fully at some later time.

Sounds good, when they are required for getting rid of
--skip-validation.

I'm not fond of the idea of doing that for all of the Doxygen warnings
about missing documentation just because it prints a warning during the
build. Seeing those warning irritate (at least me) every time you see
them, so that's some motivation to document things. I wouldn't want to
take that motivation away. :-)

If you get a list of things, where adding documentation would help for
removing --skip-validation, maybe I could write some.


Thanks,
pq