[PATCH] doc: Improve doxygen conversion

[Bill Spitzak]

On 12/19/2014 07:00 AM, Pekka Paalanen wrote:

> I like the overall reorganization here.

Thanks. Though most of the credit should go to doxygen, I noticed 
everything in it's xml output was in a much better order and decided to 
try to preserve that.

> Patch 4 adds some structs I'm not sure we should be documenting as
> external API. Patch 5 seems to attempt to hide at least map_entry.

I tried some changes to hide undocumented structures (by checking if 
they have no member functions and no description text) but it seems to 
hide ones we want to see. I think it would be easier to use \cond to 
hide the few that really should be gone.

> I'm not taking patch 5, because I believe that if we touch the
> functions' docs, we should also document them completely, rather than
> add some placeholders. Besides, the "Functions" lists is a nice place
> to see what is not documented yet.

I posted a set of 3 small patches to get the constructive parts of patch 
5, without adding memberof to any undocumented functions.

> Patch 7 I would prefer to leave for later, for a series which actually
> does improve the text.

Any suggestions for the text? I was just hoping to make it mechanically 
easier to change the text for something better, while not changing the 
output for now. I'm not sure if you want my guesses for the purposes of 
these libraries but I could try...

PS: How does an intermediate compositor, which has to both be a server 
and a client, use these two libraries at the same time? There appear to 
be some name conflicts, such as two different struct wl_display objects.