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

[Douglas Gregor]

On Jul 23, 2012, at 8:30 AM, Jordan Rose <jordan_rose at apple.com> wrote:

> 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


> Jordan
> 
> 
> On Jul 20, 2012, at 8:04 PM, Dmitri Gribenko wrote:
> 
>> On Fri, Jul 20, 2012 at 2:35 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
>>> On Fri, Jul 20, 2012 at 9:04 AM, Douglas Gregor <dgregor at apple.com> wrote:
>>>> 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
>> 
>> -- 
>> main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
>> (j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/
>> <inline-comment-render-kind-v1.patch>_______________________________________________
>> cfe-dev mailing list
>> cfe-dev at cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>