On Tue, Dec 22, 2009 at 14:30, Kenton Varda <ken...@google.com> wrote:
> 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?
I would not go with any paragraph formatting as suggested by JavaDoc,
just do a plain conversion of the comment, complete with newlines, but
with comment characters removed. So the final comment would actually
contain newlines so would need to be re-encoded with comment
characters in the particular target language if needed. If there is a
tool that generates HTML out of it, it has to include <br/> or <p> as
it pleases.
So the following comment:
> But more difficult is comments like this:
> // Blah blah blah here is a list:
> // * blah blah blah
> // * blah blah blah blah
> // * blah blah
Would become " Blah blah blah here is a list:\n * blah blah blah ..."
Note that would remove the comment characters but leave the
whitespaces in front of the comments intact. Maybe we could remove the
common prefix whitespaces (so minimum of whitespaces found on all
lines of a block).
> 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.
Garbage in, garbage out ;) So you would get a multi-line comment with
a different number of whitespaces in front of each line (maybe with
the common number of whitespaces (i.e. one) removed from all of them,
as suggested above).
> 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.
I am purely for ASCII art formatting here - this is what the developer
writes in the proto file and this it what will end up in generated
source file - so exactly what everyone would expect. If people want to
add additional formatting to make stuff look good in HTML formatting,
then they'll get it, but I don't think the protocol compiler should do
anything with it except passing through.
So in particular, a newline is added by having an empty line in a block comment
/*
* Foo
*
* Bar
*/
Leading and trailing newlines are eaten; this is equivalent to
// Foo
//
// Bar
Both would result in " Foo\n\n Bar" (maybe with the removal of the
leading space).
To accommodate other comment styles, superfluous leading comment
characters are removed as well
//// Foo
//// Bar
or
/** Foo
*** Bar
***/
will both result in " Foo\n Bar".
> Maybe you could do a survey of
> some existing .proto files to try to figure out the common patterns, and
> then detect those?
Yeah, I've seen already in descriptor.proto, that you sometimes have
multi-line post-enum-value comments ( "Not ZigZag encoded. ..."). In
my little survey of some other protocol buffers, I've seen this style
sometimes, but I think that is too fragile to support as general
documentation style. So these have to changed to pre-enum-value block
comments.
I think after the basic implementation we can easily write a JavaDoc
like HTML documentation tool; in the generated doc we then will see
comments that are off and see if things need tweaking.
-h
> 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.
>> 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.
