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

Pekka Paalanen ppaalanen at gmail.com
Wed Nov 26 03:20:30 PST 2014

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

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.


More information about the wayland-devel mailing list