[RFC wayland] doc: generate doxygen html output from the scanner

[Bryce Harrington]

On Thu, Oct 29, 2015 at 11:48:01AM +1000, Peter Hutterer wrote:
> This switches the scanner to generate doxygen-compatible tags for the
> generated protocol headers, and hooks up the doxygen build to generate server
> and client-side API documentation.
> 
> For the wayland protocol, this generates a mainpage with the copyright
> information, all interfaces are separated by doxygen groups and thus listed in
> "Modules" in the generated output.
> 
> Function, struct and #defines are documented in doxygen style and associated
> with the matching interface.
> ---
> This is an RFC for now, we need to agree on whether we want to switch to
> doxygen style first. Other changes still missing here are:
> * afaict, the summary can be dropped for most entries, it doesn't seem
>   to add any value if a long description is there
> * currently parsing too many header files, we should only parse the protocol
>   ones for a cleaner documentation.
> * future work for wayland-protocols is to add the various protocols at the
>   @page level
> * a couple of things don't have the doxygen tag yet (mostly #defines)

It would probably help to see what the doxygen output is going to look
like.  Some codebases produce nice looking reference pages, others seem to
generate doxygen that's merely marginally different than browsing the
raw source.

Does this impact the existing docbook API docs (the appendix sections)?
I think if we went this route, rather than getting rid of Docbook
entirely as I think Bill may be suggesting, it might be better to use it
strictly for the prose portion of the documentation (i.e. remove the
appendixes).  So we'd still have to have both Docbook and Doxygen, but
each would be used more for what they were designed for.  This would
still allow us to eliminate a lot of conversion code, which I suspect is
what Bill finds most advantageous with this change.

However, I'm also cognizant that while this may be an overall
improvement that may reduce frustration and confusion for future wayland
users, our current userbase may be accustomed to the API docs as they
are.  E.g. they may have bookmarks and memories about where to look for
details they need.  A sudden change might be jarring for them,
especially right now as Wayland is becoming end-user accessible on
various desktops, and bindings authors and client developers are
starting to ramp up.  But if the transition can be done smoothly, this
shouldn't be a roadblock.

So...  if this can be done to provide both the existing style docs as
well as generate a new doxygen site, then count me in as +1 for this
change.

Bryce