[protobuf] Re: Thinking of implementing: extract documentation in .proto file and store in FileDescriptorProto
On Dec 22, 4:53 pm, Henner Zeller henner.zel...@googlemail.com
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 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.
[protobuf] Re: Thinking of implementing: extract documentation in .proto file and store in FileDescriptorProto
But more difficult is comments like this: // Blah blah blah here is a list: // * blah blah blah // * blah blah blah blah // * blah blah Hmm. Javadoc would let you encode lists as ul li ... li ... / ul which would be nice, though I suppose not critical. Seems that you could just pass the html through, though. 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). Yeah. Not to repeat my other message, but @param @return etc. are important things for the accessors/setters/etc. Otherwise this won't be able to generate documentation that IDEs will find useful. Documenting private fields is of limited use, IMO. and in a lot of cases aren't even translated to the final documentation. -- 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.
Re: [protobuf] Re: Thinking of implementing: extract documentation in .proto file and store in FileDescriptorProto
On Tue, Dec 22, 2009 at 3:00 PM, Christopher Piggott cpigg...@gmail.comwrote:
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 disagree.
There are two cases:
1) The developer had the doc generator in mind when he wrote the file. In
this case, he will have written the comments according to whatever rules we
specify and therefore it is basically irrelevant what we specify.
2) The developer did not have the doc generator in mind. In that case, if
we have a special style for doc comments, presumably there won't be in any
in the file. What should we do then? Just not provide documentation? I
think that instead we should make a best effort, which means assuming that a
comment appearing immediately before a definition documents that definition.
The results won't be perfect but they are better than nothing.
So in both cases, I don't see any strong argument for forcing the developer
to mark his doc comments using a special style.
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.
This is a good point. I think the best we can do is have the javadoc
comments say something to the effect of this field is documented as:
followed by the extracted documentation. If we try to assume that the
comments from the .proto file make sense in any particular context, we're
likely to be wrong a lot of the time. For example, if your examples you
have:
/** Get ageField
* @return Age of this human
*/
public int getAgeField() { ... }
But what happens if age_field has a doc comment that is many lines long?
Then it would no longer make sense to put in the @return clause.
In fact, we should probably only embed the documentation in the getter and
then have all the other accessors simply link to the getter.
/** Get the field {...@code age_field}.
*
* pDocumentation of {...@code age_field} from {...@code something.proto}:
* pre
* [insert docs from .proto file here]
* /pre
*/
public int getAgeField() { ... }
--
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.
Re: [protobuf] Re: Thinking of implementing: extract documentation in .proto file and store in FileDescriptorProto
Hi,
On Tue, Dec 22, 2009 at 15:00, Christopher Piggott cpigg...@gmail.com wrote:
On Dec 22, 4:53 pm, Henner Zeller henner.zel...@googlemail.com
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).
I don't see much gain in having to revisit all my existing protocol
buffer files to add the information that a comment is special ;) If I
commented a field, I probably meant to, uhm, comment it - so this is
what the protocol compiler get out of it.
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.
Yeah, haven't thought too much about the target documentation yet
which will be done in each code generator explicitly. But it would go
along the lines of what you suggest. Some heuristics will evolve there
I guess (e.g. Using the first sentence as short documentation for the
field - some trick JavaDoc does).
The implementation would be two steps: first get the documentation in
the meta-data, then have the code generators generate the pretty
documentation
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 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.
