I agree, I don't think we should require a specific style for doc comments.
 Just take whatever comments appear before / on the same line as the field,
as you describe.

One tricky issue is formatting.  Javadoc requires paragraphs to be
explicitly delimited using HTML (<p>).  I've always found this really
annoying -- why can't it automatically insert paragraph breaks when it sees
blank lines?

But more difficult is comments like this:

  // Blah blah blah here is a list:
  // * blah blah blah
  // * blah blah blah blah
  // * blah blah

Or comments like this:

  // Blah blah blah, here is some example code:
  //   foo(bar);
  //   baz.qux();

Not to be confused with comments like this:

  // TODO(kenton):  Blah blah blah blah.  Note that
  //   for TODOs I indent lines after the first.  I'm not
  //   exactly sure why I do this but I always have.

Ideally I'd like to come up with reasonable rules which allow us to infer
the proper formatting for comments that already exist today, rather than
require developers to add explicit markup.  Maybe you could do a survey of
some existing .proto files to try to figure out the common patterns, and
then detect those?

On Tue, Dec 22, 2009 at 1:53 PM, Henner Zeller <henner.zel...@googlemail.com
> wrote:

> Hi,
> Since this question came up earlier today and I have this anyway on my
> TODO list, I think this is as well some nice side project for the
> holidays I could work on ;)
>
> Basically, there are two forms of comments typically found for
> messages and fields: block comments in front of the declaration of the
> message/field and a single end-of-line comment at the end of a field.
> While often block comments are regarded as a multi-line /* ... */
> block, I'd as well like to see a multi-line comment as multiple
> consecutive lines of //-style comments:
>
> /* some block
>  * comment
>  */
> message Foo {
>
>  /* some stray comment, not part of a field documentation */
>
>  /*
>   * some block comment
>   */
>  int32 some_field = 1;
>
>  int32 some_other_field = 2;  // short comment.
>
>  // Some stray comment, not part of a field. No documentation.
>
>  // Some block comment
>  // comprising of consecutive //-style comments
>  // over multiple lines with no newline in-between
>  int32 yet_another_field = 3;
> }
>
> There are several documentation styles out there such as JavaDoc or
> Doxygen that require a particular start of a comment (like /** .. */
> or /*! .. */ or ///... ). Is this a constraint we want to have or need
> ? I think this makes sense for these documentation tools as they are
> designed for code that can have some arbitrary comments in-between.
> The only requirement I'd propose is that there should be no empty line
> between a block comment and the field/message it describes. This
> enforces readability and prevents stray comments or file-header
> comments being accidentally included in the documentation.
>
> Thoughts ?
>
> H.
>
> --
>
> You received this message because you are subscribed to the Google Groups
> "Protocol Buffers" group.
> To post to this group, send email to proto...@googlegroups.com.
> To unsubscribe from this group, send email to
> protobuf+unsubscr...@googlegroups.com<protobuf%2bunsubscr...@googlegroups.com>
> .
> For more options, visit this group at
> http://groups.google.com/group/protobuf?hl=en.
>
>
>

--

You received this message because you are subscribed to the Google Groups 
"Protocol Buffers" group.
To post to this group, send email to proto...@googlegroups.com.
To unsubscribe from this group, send email to 
protobuf+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/protobuf?hl=en.


Reply via email to