Hi,
On Tue, Dec 22, 2009 at 15:00, Christopher Piggott <[email protected]> wrote:
>
>
> 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).
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 [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.
>
>
>
--
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.
