On Tue, 10 Nov 2015 14:12:48 +1000 Peter Hutterer <[email protected]> wrote:
> On Mon, Nov 09, 2015 at 09:32:52AM +0200, Pekka Paalanen wrote: > > 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. Btw. as we have same named structs in client vs. server that are different, can we choose which to link to? > > 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. > > apparently they are an md5sum of the function signature and stay the same as > long as the function signature remains constant. So you can link to them > directly, it's just going to be an ugly-looking link. > > The GENERATE_TAGFILE option generates a list of all items in xml format like > this: > <member kind="function"> > <type>struct wl_event_queue *</type> > <name>wl_display_create_queue</name> > <anchorfile>wayland-client-core_8h.html</anchorfile> > <anchor>a6607ab92946184c1ecefba21987b0a83</anchor> > <arglist>(struct wl_display *display)</arglist> > </member> > > and lo and behold this is exactly the function: > http://people.freedesktop.org/~whot/wayland-doxygen/wayland/Client/wayland-client-core_8h.html#a6607ab92946184c1ecefba21987b0a83 > > So the question now is mostly: what exactly do we want to do with this > information? :) Interesting. Makes me wonder if we could be writing links in docbook perhaps referring to the name and have a tool to use the tagfile to convert them into hash links. I think it could be nice, but not important right now. Maybe we should write some prose that could benefit from the links first. :-) > > Unless maybe if we did convert all docbook to doxygen... but I don't > > know what downsides that would have. > > Bryce pointed this out in the thread somewhere - you'd break any links to the > current documentation. Which in the case of the client/server API is IMO > low-impact, but for the rest, i.e. protocol and prose, I think docbook is > better. Ok, agreed. Keeping docbook for the prose is good. Thanks, pq
pgplWwnPQltxa.pgp
Description: OpenPGP digital signature
_______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
