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

Tue Nov 10 00:22:58 PST 2015

On 10/11/2015 18:06 , Pekka Paalanen wrote:
> On Tue, 10 Nov 2015 14:12:48 +1000
> Peter Hutterer <peter.hutterer at who-t.net> 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 <peter.hutterer at who-t.net> wrote:
>>>
>>>> On 7/11/2015 01:27 , Pekka Paalanen wrote:
>>>>> On Thu, 29 Oct 2015 11:48:01 +1000
>>>>> Peter Hutterer <peter.hutterer at who-t.net> 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
>