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

[Kristian Høgsberg]

On Tue, Sep 17, 2013 at 1:47 AM, Aaron Faanes <dafrito at gmail.com> wrote:
> 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.

I think that all sounds fine.  Thanks for digging into this.

Kristian

> -- Aaron
>
> [1] - Markdown features in Doxygen:
> http://www.stack.nl/~dimitri/doxygen/manual/markdown.html
>
> --
> Aaron Faanes <dafrito at gmail.com>