Improve Javadocs for styx-api module

[mikkokar]

This PR also adds package level API docs for com.hotels.styx.api and improves existing Javadocs for HTTP message objects.

BTW, the Javadocs can be generated locally with:

mvn javadoc:javadoc

Or specifically for the styx-api module:

mvn -f components/api/pom.xml javadoc:javadoc

[kvosper]

I have noticed a few mistakes, some are English language mistakes, some are violations of the Javadoc convention.
I have not added a comment to every single example of convention mistakes, so please apply the corrections to other Javadoc comments that contain the same mistakes.

[kvosper]

Should be "Returns all HTTP headers as {@link HttpHeaders} instances".

[mikkokar]

Why? It returns just a single HttpHeaders instance.

[kvosper]

OK, then it needs an indefinite article instead: "Returns all HTTP headers as an {@link HttpHeaders} instance".

[kvosper]

It might be better to just say "requests" instead of "request messages", even though they both make sense. I think HTTP requests are typically just referred to that way.

Perhaps we could go with "A {@link FullHttpRequest} is useful for representing requests with ..."

[mikkokar]

I'd leave it like this:

 * A {@link FullHttpRequest} is useful for requests with a
 * finite body content, such as when PUT or POST are used to create or
 * modify a RESTful object.

[kvosper]

The previous text was intended to show that it was the same builder being returned, so that chained calls can be used to set the values. The new text only tells us the type, which we already know.

Is there some builder convention we should be following?

[mikkokar]

The methods calls can still be chained even if the a new instance was returned.

Whether the builder class is mutable or immutable persistent data structure is an implementation aspect affecting all setter methods. I would describe this in the class level javadoc rather than separately in each method. Like I said it would make no difference to method chaining.

If you feel strongly about this then let's create another issue to specifically improve javadocs for the Builder classes. For now, the priority is to cover the most important gaps in the javadocs, namely 1) the HTTP message API, and (in subsequent PRs) 2) the interceptors API, and 3) application providers.

We haven't agreed on any conventions. Feel free to suggest one.

Is this the only remaining issue that is blocking this PR?