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 _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
