<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Tue, Sep 17, 2013 at 12:09 AM, Kristian Høgsberg <span dir="ltr"><<a href="mailto:hoegsberg@gmail.com" target="_blank">hoegsberg@gmail.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div class="im">On Sun, Sep 15, 2013 at 01:37:10PM -0500, Aaron Faanes wrote:<br>
> This changes the "struct foo" mentions to use <tt>, which appears as<br>
> monospaced font. This also wraps code examples with \code tags to<br>
> ensure they're detected as code.<br>
<br>
</div>Is there a doxygen markup we can use instead of <tt>?  Most of the<br>
<tt> uses are for types that doxygen should have a tag for, I<br>
believe.  And if we have to use html, maybe <code> is better?<br></blockquote><div><br></div><div>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. :)<br>

<br></div><div>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.<br>

<br></div><div>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.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">


<div class="im"><br>
> The code example uses C++ style // comments. I would have preferred to<br>
> use /* */ comments for consistency, but this is not possible since we're<br>
> already in this type of block comment. Doxygen picks it up fine,<br>
> however.<br>
<br>
</div>Perhaps we could use &#47; instead of a literal / ?<br></blockquote><div><br></div><div>Unfortunately, it doesn't seem possible to get Doxygen not to escape the ampersand in &#47; unless it's within a \htmlonly block. On top of that, a \code block disables Doxygen commands, so \htmlonly sadly isn't available.<br>

<br></div><div>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:<br>

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

 * \comment{Accessor access}<br> * wl_event_loop *loop = ...;<br> * wl_event_loop_add_destroy_listener(loop, &your_listener);<br> * ~~~<br></div><div><br></div><div>ALIASES += comment{1}="/* \1 *<!-- -->/"<br>

<br></div><div>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.<br>

<br></div><div>-- Aaron<br></div><div><br>[1] - Markdown features in Doxygen: <a href="http://www.stack.nl/~dimitri/doxygen/manual/markdown.html">http://www.stack.nl/~dimitri/doxygen/manual/markdown.html</a><br></div><br clear="all">

</div>-- <br>Aaron Faanes <<a href="mailto:dafrito@gmail.com" target="_blank">dafrito@gmail.com</a>>
</div></div>