[PATCH] Comment parsing: rendering kind field for inline command

Here, we're classifying a subset of the Doxygen inline commands. Can you extract this operation out into a member function of InlineCommandComment, something like

[...]

or maybe tie it to the rendering of the text, e.g.,

        enum CXInlineCommandRenderKind {
                ICR_Normal,
                ICR_Bold,
                ICR_Code,
                ICR_Emphasized
        }

        CXInlineCommandRenderKind getRenderKind() const;

so that all clients don't need to reinterpret the various Doxygen/HeaderDoc/etc. commands themselves (Unless they want to)? This information would be useful in the libclang API as well, since we expect many clients to use that.

Agreed. I like the second option better because Doxygen manual
assigns some semantic difference to the commands which are rendered
the same way. For example, \c is "anything that looks like code", but
\p is "parameter name".

I will do it as a follow-up because I think it makes sense to make
CommentSema responsible for such analysis and touching that is a
little out of scope for this patch.

Attached is a patch that implements this proposal.

Please review.

Dmitri

inline-comment-render-kind-v1.patch (14.9 KB)

LGTM!

Bikeshedding: ICR_Monospaced or ICR_FixedWidth instead of ICR_Typewriter, since it's 2012.

Less bikeshedding: although we're conditioned to think of code in a monospace font, there's not really a /reason/ for that. (Smalltalk and AppleScript traditionally use non-monospaced fonts for code listings...not that those are necessarily relevant for us.) In HTML this is the (often not observed) difference between <code> and <tt> (like <em> and <i>). In Doxygen and other documentation systems, does "\c" mean "code" or "fixed-width"?

(I'm inclined to think "code", and thus go with Doug's original listing, and emit <code> rather than <tt>.)
Jordan

Bikeshedding: ICR_Monospaced or ICR_FixedWidth instead of ICR_Typewriter, since it's 2012.

Less bikeshedding: although we're conditioned to think of code in a monospace font, there's not really a /reason/ for that. (Smalltalk and AppleScript traditionally use non-monospaced fonts for code listings...not that those are necessarily relevant for us.) In HTML this is the (often not observed) difference between <code> and <tt> (like <em> and <i>). In Doxygen and other documentation systems, does "\c" mean "code" or "fixed-width"?

(I'm inclined to think "code", and thus go with Doug's original listing, and emit <code> rather than <tt>.)

Doxygen's documentation says "using a typewriter font", and specifically mentions <tt>.

I slightly prefer the term 'Monospaced' to 'Typewriter', but only slightly.

  - Doug

Thank you Douglas and Jordan for reviews! Committed r160633 with
s/Typewriter/Monospaced/.

Dmitri

Monospace is what font people will look for rather than typewriter for sure :slight_smile:

-eric

tt doesn't stand for anything as old fashioned as a typewriter, it refers to one of these newfangled teletype machines.[1]

David

[1] http://www.w3.org/TR/1999/REC-html401-19991224/present/graphics.html#h-15.2.1