headers
Dmitri Gribenko | 21 Jul 2012 05:04
Picon

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

On Fri, Jul 20, 2012 at 2:35 PM, Dmitri Gribenko <gribozavr@...> wrote:
> On Fri, Jul 20, 2012 at 9:04 AM, Douglas Gregor <dgregor@...> 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.
(Continue reading)

Permalink | Reply |
headers
Douglas Gregor | 23 Jul 2012 08:03
Picon
Favicon

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

LGTM!

Sent from my iPhone

On Jul 20, 2012, at 8:04 PM, Dmitri Gribenko <gribozavr@...> wrote:

> On Fri, Jul 20, 2012 at 2:35 PM, Dmitri Gribenko
<gribozavr@...> wrote:
>> On Fri, Jul 20, 2012 at 9:04 AM, Douglas Gregor <dgregor@...> 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
(Continue reading)

Permalink | Reply |
headers
Jordan Rose | 23 Jul 2012 17:30
Picon
Favicon

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

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

On Jul 20, 2012, at 8:04 PM, Dmitri Gribenko wrote:

> On Fri, Jul 20, 2012 at 2:35 PM, Dmitri Gribenko
<gribozavr@...> wrote:
>> On Fri, Jul 20, 2012 at 9:04 AM, Douglas Gregor <dgregor@...> 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;
>>>
(Continue reading)

Permalink | Reply |
headers
Douglas Gregor | 23 Jul 2012 17:40
Picon
Favicon

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


On Jul 23, 2012, at 8:30 AM, Jordan Rose <jordan_rose@...> 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@...> wrote:
>>> On Fri, Jul 20, 2012 at 9:04 AM, Douglas Gregor <dgregor@...> 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
>> [...]
(Continue reading)

Permalink | Reply |
headers
Dmitri Gribenko | 23 Jul 2012 18:45
Picon

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

On Mon, Jul 23, 2012 at 8:40 AM, Douglas Gregor <dgregor@...> wrote:
>
> On Jul 23, 2012, at 8:30 AM, Jordan Rose <jordan_rose@...> 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.

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

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@...>*/
Permalink | Reply |
headers
Eric Christopher | 23 Jul 2012 22:27
Picon
Favicon

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


On Jul 23, 2012, at 9:45 AM, Dmitri Gribenko <gribozavr@...> wrote:

> On Mon, Jul 23, 2012 at 8:40 AM, Douglas Gregor <dgregor@...> wrote:
>> 
>> On Jul 23, 2012, at 8:30 AM, Jordan Rose <jordan_rose@...> 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.
> 
> Thank you Douglas and Jordan for reviews!  Committed r160633 with
> s/Typewriter/Monospaced/.

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

-eric
Permalink | Reply |
headers
David Chisnall | 23 Jul 2012 23:09
Picon
Favicon

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

On 23 Jul 2012, at 16:40, Douglas Gregor wrote:

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

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
Permalink | Reply |

Gmane