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 [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/protobuf?hl=en.
