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

[Peter Hutterer]

CC-ing Tiago for the doxygen question

On Wed, Nov 04, 2015 at 03:30:29PM -0800, Bryce Harrington wrote:
> On Mon, Nov 02, 2015 at 10:27:54AM +1000, Peter Hutterer wrote:
> > 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/
> 
> Nice!  I personally find this a lot more approachable as a reference.
> But I haven't done any compositor or wayland client development so don't
> weigh my opinion very highly here...  would be nice to get feedback from
> people actually using these docs.
>  
> > > 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 :)
> 
> Yeah you're right, that does look good.  Or at least, it avoids the
> technobabble barf that I've sometimes seen from doxygen.  The docs
> themselves are on the spotty side, but what's new.
> 
> > 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.
> 
> That sounds like it'd be useful.
> 
> The pages.html page seems like it provides a concise listing, but having
> one set of links to describe the objects (with a nice description but no
> technical details) and a separate set of links for the object interface
> docs (with technical details but no description) seems like it breaks
> things up a bit much.  I wonder if it'd be more readable if instead of
> two separate pages, there was one with the object description at the top
> and the interface technical details below.
> 
> But in any case that's minor, at least one can click through to get all
> the various info.

that split with the extra click is a limitation of doxygen. a page is simply
a separate item though you can push it into a 2-level hierarchy with
subpage. When you do that, the link is always to the page, you can't link
straight to an interface here.

There's ways to fake that by having the actual page provide the description
of the interface as well, but direct linking isn't possible, sorry.

> > > 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.
> 
> Ok, so if this round of changes adds doxygen while leaving publican
> unchanged, that seems rather uncontroversial and I feel we can go ahead
> and put this in now.
> 
> > 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.
> 
> Yeah I agree, and that's a good point.  I wouldn't be at all opposed to
> dropping this.  If we can do that as a follow up patch, then it'd make
> it easier to get wider visibility on the change, in case anyone has
> reservations about it.
> 
> Do you know why the API docs were added to the publican doc in the first
> place?  Was it simply to make sure the docs existed somewhere, or was
> there a specific need e.g. like being able to have them in a more easily
> printed format?  Or...?

the publican doc was the one doc source, both for the PDF and the website.
I suspect Tiago's intent (e2db4cf) was simply to add more useful stuff to
it, at the cost of a doxygen run and an xsl transformation.
And it works, the server/client library both are there and documented, we're
just missing the actual protocol bits :)

Cheers,
   Peter