[PATCH 5/6] utils: Ensure wl_list's doxygen formats properly

[Aaron Faanes]

On Tue, Sep 17, 2013 at 12:09 AM, Kristian Høgsberg <hoegsberg at gmail.com>wrote:

> On Sun, Sep 15, 2013 at 01:37:10PM -0500, Aaron Faanes wrote:
> > This changes the "struct foo" mentions to use <tt>, which appears as
> > monospaced font. This also wraps code examples with \code tags to
> > ensure they're detected as code.
>
> Is there a doxygen markup we can use instead of <tt>?  Most of the
> <tt> uses are for types that doxygen should have a tag for, I
> believe.  And if we have to use html, maybe <code> is better?
>

For a single word, Doxygen's \c would be used, but it doesn't extend beyond
that word. Doxygen recommended <tt> for multi-word code, so I naively went
with it without thought. :)

Digging into it, a better option could be backticks, as they behave like
<code> blocks. This is a Markdown-inspired feature added to Doxygen[1] in
~April 2012; I mention this in case there's a preference for supporting old
Doxygens.

In any case, the actual struct or class will be linked up if it has
documentation. The backticks are solely for monospacing the "struct" prefix.


>
> > The code example uses C++ style // comments. I would have preferred to
> > use /* */ comments for consistency, but this is not possible since we're
> > already in this type of block comment. Doxygen picks it up fine,
> > however.
>
> Perhaps we could use / instead of a literal / ?
>

Unfortunately, it doesn't seem possible to get Doxygen not to escape the
ampersand in / unless it's within a \htmlonly block. On top of that, a
\code block disables Doxygen commands, so \htmlonly sadly isn't available.

The good news is I came up with a hackish solution I found to get /* */
output properly in HTML, XML, and manpages (and probably the other
formats). The trick is using ~~~ (another Markdown feature) for code
blocks, instead of \code, and defining a Doxygen alias to output a
specially crafted string:

 * ~~~
 * struct wl_listener your_listener;
 * your_listener.notify = your_callback_method;
 *
 * \comment{Direct access}
 * wl_signal_add(&some_object->destroy_signal, &your_listener);
 *
 * \comment{Accessor access}
 * wl_event_loop *loop = ...;
 * wl_event_loop_add_destroy_listener(loop, &your_listener);
 * ~~~

ALIASES += comment{1}="/* \1 *<!-- -->/"

So the trade-off here is that the output is correct and consistent, but
there's a bit of weirdness on the input side. If this sounds reasonable,
I'll rework my patches to use it instead of the C++ style.

-- Aaron

[1] - Markdown features in Doxygen:
http://www.stack.nl/~dimitri/doxygen/manual/markdown.html

-- 
Aaron Faanes <dafrito at gmail.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20130917/de2869c1/attachment-0001.html>