On Sat, 7 Nov 2015 09:53:10 +1000 Peter Hutterer <[email protected]> wrote:
> On 7/11/2015 01:27 , Pekka Paalanen wrote: > > On Thu, 29 Oct 2015 11:48:01 +1000 > > Peter Hutterer <[email protected]> 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) > >> > >> doc/doxygen/Makefile.am | 22 +++++- > >> doc/doxygen/wayland.doxygen.in | 4 +- > >> src/scanner.c | 165 > >> ++++++++++++++++++++++++++--------------- > >> 3 files changed, 130 insertions(+), 61 deletions(-) > > > > Hi Peter, > > > > this is a cool idea. I still haven't grasped all the details, but I > > think we could use the following sets of "appendices" to the Wayland > > documentation (prose): > > > > A. language-agnostic protocols docs > > B. libwayland library API docs, server and client separated > > C. protocol C bindings docs, server and client separated > > > > A and B are what we already have in some form, and C is what you are > > now adding. Excellent! > > > > A is generated directly from XML, and intended for people working on > > other language bindings than our C bindings (when we get part C for > > people working in C). > > > > B is generated through Doxygen scanning non-generated code. It is > > useful to keep the C bindings docs out of this, so that people writing > > other language bindings have a coherent doc and they don't need to > > check whether a function listed is something they are supposed to use > > or not (i.e. generated or not). > > fwiw, it'd be possible to scan the core libraries as well and put them > in a separate doxygen group/page. That way they'd resolve internally > (e.g. an arg of type wl_resource) but still be separated in the doc. Hi Peter, sounds good. > > A and C contain basically the same information, just laid out > > differently: C talks in the proper C function and type names, while A > > uses just the protocol names. C is further duplicated between server > > and client docs. > > > > I'm not sure if we need server:B+C and client:B+C docs as such, since I > > don't think there are many references between B and C. It might be > > enough to have one TOC page for "server" and one for "client" which > > then somehow link to B and C parts. > > > > Anyway, that's just random thoughts. > > > > What I would really like is a way to have links to A, B (and C) from the > > *prose*. Looks like we can already have links to A at least. > > > > What bothers me in the current B from a user point of view is that I > > don't know how to get a link to a specific function's documentation. I > > don't think there is a TOC listing all functions, and when I find the > > function I'm looking for, I can't take a link to it for e.g. pasting in > > IRC. Doxygen docs themselves have all the links and TOCs, but the > > conversion to docbook loses too much currently. > > I think this should be possible to extract with a bit of xsl tweaking, > I'll try to look into that. > > One problem with doxygen though is that you can't link directly to a > function from external sources, the anchors are hashes rather than > function names. You can only link to a page, a group and a struct. Bummer. I was hoping that there might be some way to create those links when passing everything including the prose through a single tool at once, but I suppose that's not really possible if there is no output mode in Doxygen that didn't use hashes as the anchors. And if the hashes are too unstable to use - I think I recall seeing them change for no good reason. Unless maybe if we did convert all docbook to doxygen... but I don't know what downsides that would have. > > Ah, I hope I gave some ideas. Interesting work! > > > > When you say "whether we want to switch to doxygen style", do you mean > > that we'd drop the conversion to docbook? Would we be working towards > > completely replacing docbook with only doxygen? > > No, the current docbook is untouched. The difference is simply that we > have a different doc style in the scanner sources that doesn't work for > doxygen (e.g. @foo instead of @param foo). AFAICT we're not using that > style for anything, so switching to doxygen won't hurt us there. Sure. I wonder if the old scanner generated comment format follows kerneldoc instead, maybe it was just a thinko. I had always assumed it was already doxygen format, just unused by us. That conversion part is definitely Acked-by me. > And since docbook is generated from doxygen, any additional info we > generate that's doxygen compatible will benefit the docbook conversion. Cool. > > I applied this patch and tried to build it, but it seems it generates > > object destructor functions twice, e.g. wl_buffer_destroy, so the build > > fails. > > Weird. Then again, this was just an RFC patch :) Have a look at the new > patch I sent out, that one works properly and generates nicer output in > general > > http://lists.freedesktop.org/archives/wayland-devel/2015-November/025238.html I'll try. :-) Thanks, pq
pgpivVma69jnk.pgp
Description: OpenPGP digital signature
_______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
