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

[Peter Hutterer]

On Fri, Oct 30, 2015 at 03:40:33PM -0700, Bryce Harrington wrote:
> 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.  

wish, command, yours, mine, etc.
http://people.freedesktop.org/~whot/wayland-doxygen/

> Some codebases produce nice looking reference pages, others seem to
> generate doxygen that's merely marginally different than browsing the
> raw source.

>From the libinput doxygen experience, I found that 90% of "nice looking" [1]
efforts are achieved by using @ingroup, because it groups everything that
should belong together into one page. This patch does a @defgroup for each
interface and then an @ingroup, so you get this:
http://people.freedesktop.org/~whot/wayland-doxygen/Client/group__iface__wl__pointer.html
That's anything to do with wl_pointer in one page, including the defines
(not all of them though). Lack of documentation here is caused by lack of
documentation in the actual protocol though :)

The @page and @subpage handling also provides this:
http://people.freedesktop.org/~whot/wayland-doxygen/Client/pages.html
Not that useful for core wayland, but for the wayland-protocols repo, each
protocol would have a first-level list, with the interfaces as second-level
items.

> 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.

I agree, I'd drop the server/client API bits from docbook and refer to
doxygen instead, see my comment below though.

> 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.

diff says that the xml files we feed to publican are the same before/after,
with the exception of some items that are now linked but weren't before.
Not too surprising, publican gets the xml files from doxygen so if
we confince doxygen to recognise the source code better, we get better
results.

but: the current API docs in publican are useless. look at appendix B, the
"client API". http://wayland.freedesktop.org/docs/html/apb.html
it's technically the client API but it's lacking anything that's not core
libwayland API. it doesn't describe protocol interfaces at all. That's only
in the protocol spec (Appendix A) and that is generated straight from the
xml without doxygen's involvement.

The doxygen output in this patch only does the protocol interfaces. so there
isn't even an overlap between these new ones and the current ones, but the
new ones could be made to include the core libwayland bits too.

Cheers,
   Peter

[1] I don't mean visually here, just organization-wise