docs: Overhaul javadocs, using Oracle's styleguide

[jamierocks]

I do not know what your stance on work-in-progress pull requests is - apologies if its don't make them. However, I believe that this pr could well do with community input throughout its development, to ensure that the javadocs are well made - hence opening the pr earlier that I normally would.

This pr should address #130.

---

This pull request aims to accomplish two objectives:

1. Provide a strong set of javadocs, that complement the method name rather than regurgitate it.
2. To fully utilize the capabilities of javadocs, to ensure once compiled they can aid developers in using sendgrid-java.

---

See http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide

[SendGridDX]

All committers have signed the CLA.

[thinkingserious]

Hi @jamierocks,

Thank you! No problem at all with WIP :)

With Best Regards,

Elmer

[jamierocks]

Hi @thinkingserious,

Glad to hear that ;) I was wondering if you have an IRC channel, or another way of real-time communication - I would quite like to discuss some other potential pull requests with you.

Regards,
Jamie

[thinkingserious]

Hi @jamierocks,

Could you please shoot us an email at [email protected] so we can add you to a Slack channel we use?

With Best Regards,

Elmer

[jamierocks]

Hi @thinkingserious,

I sent an email your way and still haven't got any invite to the Slack channel :(
Concerning the pr, whats the procedure like for merging at sendgrid? (is there anything I need to do? wait for feedback, etc)

Regards,
Jamie

[mbernier]

We are just really behind on all the things - it's been a crazy month!

Since you have been looking at javadoc - I found this in another build and I'm curious if this is related to this PR?

:javadoc/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:205: warning: no @return
    public Builder withType(String type) {
                   ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:214: warning: no @return
    public Builder withDisposition(String disposition) {
                   ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:223: warning: no @return
    public Builder withContentId(String contentId) {
                   ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:231: warning: no @return
    public Attachments build() {
                       ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/SendGridAPI.java:18: error: @param name not found
   * @param apiKey is your SendGrid API Key: https://app.sendgrid.com/settings/api_keys
            ^
1 error
4 warnings
:javadoc FAILED
FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':javadoc'.
> Javadoc generation failed.
* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.
BUILD FAILED
Total time: 18.18 secs
The command "eval ./gradlew assemble " failed. Retrying, 2 of 3.
The TaskContainer.add() method has been deprecated and is scheduled to be removed in Gradle 2.0. Please use the create() method instead.
:compileJava UP-TO-DATE
:processResources UP-TO-DATE
:classes UP-TO-DATE
:fatJarPrepareFiles UP-TO-DATE
:fatJar UP-TO-DATE
:jar UP-TO-DATE
:javadoc/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:205: warning: no @return
    public Builder withType(String type) {
                   ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:214: warning: no @return
    public Builder withDisposition(String disposition) {
                   ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:223: warning: no @return
    public Builder withContentId(String contentId) {
                   ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:231: warning: no @return
    public Attachments build() {
                       ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/SendGridAPI.java:18: error: @param name not found
   * @param apiKey is your SendGrid API Key: https://app.sendgrid.com/settings/api_keys
            ^
1 error
4 warnings
:javadoc FAILED
FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':javadoc'.
> Javadoc generation failed.
* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output.
BUILD FAILED
Total time: 7.54 secs
The command "eval ./gradlew assemble " failed. Retrying, 3 of 3.
The TaskContainer.add() method has been deprecated and is scheduled to be removed in Gradle 2.0. Please use the create() method instead.
:compileJava UP-TO-DATE
:processResources UP-TO-DATE
:classes UP-TO-DATE
:fatJarPrepareFiles UP-TO-DATE
:fatJar UP-TO-DATE
:jar UP-TO-DATE
:javadoc/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:205: warning: no @return
    public Builder withType(String type) {
                   ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:214: warning: no @return
    public Builder withDisposition(String disposition) {
                   ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:223: warning: no @return
    public Builder withContentId(String contentId) {
                   ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/helpers/mail/objects/Attachments.java:231: warning: no @return
    public Attachments build() {
                       ^
/home/travis/build/sendgrid/sendgrid-java/src/main/java/com/sendgrid/SendGridAPI.java:18: error: @param name not found
   * @param apiKey is your SendGrid API Key: https://app.sendgrid.com/settings/api_keys
            ^
1 error
4 warnings
:javadoc FAILED
FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':javadoc'.
> Javadoc generation failed.

[jamierocks]

Fair enough - you've had an insane amount of prs to go through.

This pr builds with no javadoc issues, although there might be issues with recent upstream changes - I'll rebase the pr when I'm at my dev machine.

[thinkingserious]

@jamierocks

We have not been able to merge your Pull Request, but because you are awesome - we wanted to make sure you could still get a SendGrid Hacktoberfest shirt.

Please go fill out our swag form before Nov 5th and we will send the shirt! (We know that you might have tried this before and it didn’t work, sorry about that!)

You have till Nov 5th to fill out this form in order to get the Hacktoberfest shirt!

Thank you for contributing during Hacktoberfest! We hope to see you in the repos soon! Just so you know, we always give away a SendGrid shirt for your first ever non-Hacktoberfest PR that gets merged.

[jamierocks]

So this popped up on my mobile feed, this PR was ready to merge. I'm not sure whether this PR is now as comprehensive as it once was, or if it needs to be rebased again to be merged. I'll take a look when I get back :)

[thinkingserious]

Thanks @jamierocks!

[jamierocks]

Going over my open PRs, looks like this could be merged?

[childish-sambino]

LGTM. Nice work.

[childish-sambino]

@jamierocks Just realized this was based on the refactor branch. Was this intentional? If not, could you submit a new PR for adding these changes to master?

[jamierocks]

@childish-sambino I'm going to guess at the time this was intentional, but clearly not now. That could explain why it still cleanly applies after a year though I guess.

I'll see the damage tomorrow - hopefully it should be a clean cherry-pick, see what javadoc warnings/errors are present, and make any final adjustments.