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

[Pekka Paalanen]

On Wed, 26 Nov 2014 11:24:28 -0800
"Jon A. Cruz" <jonc at osg.samsung.com> wrote:

> 
> 
> On 11/26/2014 10:22 AM, Bill Spitzak wrote:
> > On 11/25/2014 11:52 PM, Pekka Paalanen wrote:
> > 
> >> Or are duplicates perhaps due to us having, say, struct wl_display a
> >> different thing on server vs. client?
> > 
> > The duplicates are due mostly to wl_list (and similar things) being
> > documented twice. But I think doxygen does generate some identical tags
> > for the server and client documentation. The solution may be to edit one
> > of these and add an extra letter to all the tags so there are no
> > conflicts. Telling doxygen to document both in one pass caused it to mix
> > all the calls together, probably a bad idea.
> 
> I definitely think this sounds like an issue I should look into. One of
> the projects I worked on was to figure out how to create design
> documents from doxygen, and to coordinate design docs from multiple
> teams working on multiple projects/features.
> 
> One key to getting overall documentation to work was to coordinate
> identifiers to either end up with different ones or unified ones on a
> case by case basis.
> 
> The *ideal* would be to get a single unified Doxygen pass working.
> However, it does warrant investigation as to how close to that a
> pragmatic solution appropriate to Wayland would get us. Two passes is
> not that bad. Once I start to get details and options figured out it
> definitely looks like Bill will be able to give feedback and guidance.

Please do.

If you need it, it is perfectly ok to have server and client side
passes separate. I'd like them to be separate HTML pages, too. It
doesn't hurt, if we happen to get duplicate documentation for things
like wl_list, one for server and one for client. The important thing is
to never mix up server stuff with client stuff.

Btw. libwayland-cursor is client side stuff and a separate library.

For example: struct wl_display is very different between server and
client. 

Struct wl_buffer has three completely different meanings:

- client side public API: it is a syntactic type without an actual
  definition: the real struct behind it is wl_proxy.

- server side public API: it is a deprecated real type with public
  members.

- libwayland internal API: a ring byte buffer, completely contained in
  src/connection.c, used by both server and client side internal code.

Luckily connection.c probably should not be included in the generated
docs, so we can overlook the third meaning.


Thanks,
pq