On Dec 22, 4:53 pm, Henner Zeller <[email protected]>
wrote:
> /*
> * some block comment
> */
> int32 some_field = 1;
> int32 some_other_field = 2; // short comment.
I would be fine with that, but I also woudn't have a problem with you
requiring everything be a block, because you can still do it on one
line:
/**
* some block comment
*/
int32 some_field = 1;
int32 some_other_field = 2; /** short comment */
Notice I did keep the /** in there, because:
> Is this a constraint we want to have or need
I think so. I think it's helpful to say "This comment is special." I
can see a good argument, though, that it's redundant - especially if
"pass documentation comments to generated code" is a .proto file
"option." I like /** something */ because it fits well with java and
C/C++ (with Doxygen) and because I think the Python triple-quote is
ugly. If you really wanted // then I'd be happiest with ///
Ultimately, though, the .proto is its own language, so decide upon
whatever makes sense to you. It shouldn't be overly cumbersome or
ugly, and it should be reasonably easy for the .proto parsing code to
handle (so you don't wind up hating me).
> 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.
I agree.
There are some other things you didn't ask that are bothering me a
little. One has to do with fields. The fields themselves, at least
in java, are private, so documenting them in this way is not
especially useful. What you really want is to have these documents
put something meaningful in the .hasSomething(), .getSomething
(), .getSomethingCount(), etc. and in the builder, to .setSomething()
and .addSomething(), and similar methods.
How to make this work and "look good" is a real question in my mind.
If you do:
message Something {
required int32 ageField = 1; /** Age of this human */
}
what you really would want for "useful inline documentation" (using
javadoc as an exapmle, but same for Doxygen) would be something like
/** Get ageField
* @return Age of this human
*/
public int hasAgeField() { ... }
for the builder:
/** Set ageField
* @param value Age of this human
*/
public void setAgeField(int value) { ... }
and similar for lists etc. The "ageField" part I grabbed from the
field name, and the actual comment I applied to the @return and
@param.
I would have to take some time to think about how you would phrase
this so that it makes sense for lists.
This is kind of where I was going / what I was wishing for with regard
to fields. The decisions are a little more straight-forward when it's
documentation for messages, as that documentation I would expect to
more or less pass straight through unchanged, and use it to document
the classes being generated. (The fields are just more complicated,
since the actual fields in the class are private).
I'm not sure where you'd go with services - method calls I suppose,
but for java/doxygen those would be the form @param @param ...
@return. I don't really know python/php so I'm not sure how this maps
over to those languages.
Is that helpful?
--
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.
