On 10/11/2015 18:06 , Pekka Paalanen wrote:
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?
yes. the makefile hooks are set up that so that the two are split into
html/Client/... and html/Server/... output directories. they're entirely
separate. That's not a doxygen thing in itself, it's simply run twice,
once with the client headers as input, once with the server headers as
input.
Cheers,
Peter
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
_______________________________________________
wayland-devel mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
