On Tue, Sep 17, 2013 at 1:47 AM, Aaron Faanes <[email protected]> wrote: > On Tue, Sep 17, 2013 at 12:09 AM, Kristian Høgsberg <[email protected]> > 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 <[email protected]> _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
