On Tue, Dec 22, 2009 at 3:00 PM, Christopher Piggott <cpigg...@gmail.com>wrote:

> > 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}.
   *
  * <p>Documentation 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.


Reply via email to