[libvirt] [PATCH] Move comment after enum members

[Claudio Bley]

At Thu, 10 Jan 2013 12:42:14 +0100,
Claudio Bley wrote:
> 
> At Wed, 09 Jan 2013 18:06:51 -0700,
> Eric Blake wrote:
> > 
> > Hmm, I wonder if we should instead fix the doc-generation parser.  I'm
> > used to the style:
> > 
> > ONE, /* short comment for one */
> > /* longer comment for two */
> > TWO,
> > THREE, /* and short for three again */
> 
> I think this won't work reliably. All you see in the parser is COMMENT
> and NAME tokens.
> 
> You could only special case on two consecutive comments and then
> assign the second to the current member.
> 
> Otherwise, what we could do is change the style rules and use the
> comma as a separator:
> 
> ONE /* short comment for one */,
> /* longer comment for two */
> TWO,
> THREE /* and short for three again */,
> 
> That way the association would be unambiguous. But I could imagine
> what you're saying - that's ugly... It would require changing all
> existing comments.
> 
> Another alternative I can think of would be to use a special marker
> for "postfix" comments (like oxygen):
> 
> ONE, /*< short comment for one */
> /* longer comment for two */
> TWO,
> THREE, /*< and short for three again */
> 
> This would also require changing all existing comments, unless we
> introduce a special marker for "prefix" comments...
> 
> So, having said all that, here's another idea:
> 
> --- >8 ----
> Subject: [PATCH] docs: Differentiate long and short comments inside enums
> 
> Regard a comment containing newline characters as a long comment
> associating to the current member, otherwise it's just a short comment
> associated with the previous member.

Um, this doesn't work so well. Sometimes "short" comments span several
lines, sometimes "long" comments are quite short...

The only difference between them is the comment is on the same line as
the enum member for "short" comments, otherwise on a line of its own.

If the parser would track line numbers this would be easy...

Claudio
-- 
AV-Test GmbH, Henricistraße 20, 04155 Leipzig, Germany
Phone: +49 341 265 310 19
Web:<http://www.av-test.org>

Eingetragen am / Registered at: Amtsgericht Stendal (HRB 114076)
Geschaeftsfuehrer (CEO): Andreas Marx, Guido Habicht, Maik Morgenstern