Re: [cdt-dev] JavaDoc

[Marc Khouzam <marc.khouzam@xxxxxxxxxxxx>]

> -----Original Message-----
> From: cdt-dev-bounces@xxxxxxxxxxx 
> [mailto:cdt-dev-bounces@xxxxxxxxxxx] On Behalf Of Jason Litton
> Sent: Monday, May 21, 2012 11:20 AM
> To: CDT General developers list.
> Subject: [cdt-dev] JavaDoc
> 
> In my first gerrit code review, Marc asked for JavaDoc on one 
> line, but I'm really not sure what I should be adding. 
> I haven't done much with Java Doc. Are we looking for an @see 
> tag there, or something else? If someone could give me an 
> idea, I'd appreciate it. The gerrit review is here 
> https://git.eclipse.org/r/#/c/5972/

We're still feeling our way around Gerrit, but here is what I
think should be done in the case where a contributer has questions
about review comments.

You can answer any of the review comments by looking at the file
where the comment is; once you've done that for the comments
you wanted to answer/clarify, you then click on the 'Review' button
of the patchset (even though is has already been reviewed), 
and then publish the comments (Publish coments button).

Note that the same patch set can be reviewed multiple times by 
different people, or even by the same person, so as to add more 
comments, or answer/update existing comments.  All these changes
will be sent by email to the current reviewers.

So, in this particular case, you could update that one comment
about javadoc to ask for clarification and then review->publish.
This will keep all discussion of the review within the review
itself.  

Another option is to ask in the bugzilla, which also helps keep
the review contained.

In this particular case though, since we're here already, let
me answer right away :)

Any new API (class, method, member), should have a short description
of what it is meant to be used for.  It should be written towards
a reader that will use that new API.  You can look at most of the
other classes to find such javadoc as examples.

Thanks

Marc