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

[Bryce Harrington]

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.

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

Bryce