Implement ack and nack methods, add javadoc and tests

[mziccard]

This PR implements ack and nack methods, adds javadoc and unit tests. System tests will come as soon as pull methods are implemented.

[coveralls]

Coverage increased (+0.08%) to 84.374% when pulling 264755c on mziccard:pubsub-ack-nack into b872399 on GoogleCloudPlatform:pubsub-alpha.

[lesv]

Once I understand (or get feedback from JJ or Arie) the javadoc story for the repo, I expect to give quite a bit of feedback.

The code and the testing look ok, but I want to spend a few minutes at an earlier time of day re-reviewing to make sure that I believe your tests actually cover things and are helpful.

[aozarov]

I think so far we were careful to follow the correct Javadoc guidlines for structure (spaces, tag ordering) and rules (punctuation, case,..). As for the descriptions, I think the focus was on clarity which in some
cases made it less concise. You can find in both the JDK and Guava examples to match either style.
I don't have strong opinion about it, however if you think clarity is not effected or even improved by making it shorter than I think you should go for it.

BTW, Looking at the generated Javadoc it looks like @param descriptions are not enabled.

[mziccard]

BTW, Looking at the generated Javadoc it looks like @param descriptions are not enabled.

Arie, what do you mean with this?

[aozarov]

Arie, what do you mean with this?

I was wrong. I sampled few places (just to see how things look like per earlier discussion) and unfortunately each of these did not specify @param...
E.g. this and this and this and more...

[lesv]

Our internal guidelines specify that it should be a fragment, not a sentence and that it's ok to not use @param if you mention the value in the paragraph. It also specifies fewer words (ie. fragments) are better as long as it's clear.

So, I'm going to suggest a few re-wordings to be simpler - we won't go through and change existing stuff, but I think being concise is better for our users.

[mziccard]

Not to be picky but let me clarify. Fragments are sequences of words that look like a sentence but are not. The difference from a sentence is that fragments are allowed to contain no independent clauses. An independent clause is a sequence of words that contains a subject and a verb and makes sense by itself (extrapolated from the context).

Acknowledges the given messages for the provided subscription. is already a fragment (it's missing the subject). @lesv suggestion (Acknowledges given messages for provided subscription.) simply removes the articles but does not affect its fragment nature.

For what concerns @param descriptions, according to Oracle's guide, they should start with a noun (hence the suggested @param subscription whose messages are being acknowledged is wrong), possibly preceded by an article.

I don't mind applying changes (even project-wide) if that improve docs readability I just doubt that removing some articles or conjunctions would help users.

[lesv]

Yep - I agree - It's what I've been pondering. I do dislike several mentions of the same thing for the future. LGTM

[mziccard]

Thanks for the pass @lesv