Improve documentation of hk2-inhabitant-generator

[glassfishrobot]

According to https://java.net/projects/hk2/lists/users/archive/2013-12/message/3 in order to use the @Service annotation we must run the hk2-inhabitant-generator.

This is problematic because:

1. I don't remember seeing a mention of this anywhere, though on second scan I now see it is mentioned once at https://hk2.java.net/2.2.0-b25/getting-started.html. This should be documented at least once in every document that mentions @Service or, better yet, just document it in the @Service Javadoc.
2. The use of the word "habitant" is confusing. It is my understanding that this is left over from HK 1.0. Please consider renaming this tool to hk2-service-generator or something along those lines.
3. The documentation asks us to invoke ServiceLocatorUtilities.createAndPopulateServiceLocator but Jersey doesn't give us the option of doing so and the documentation doesn't mention of populating a pre-existing ServiceLocator. I understand how to get this working but end-users shouldn't have to dig through the source-code to figure this out.

   Affected Versions

   [2.2.0]

[glassfishrobot]

• Issue Imported From: https://github.com/javaee/hk2/issues/209
• Original Issue Raised By:@glassfishrobot
• Original Issue Assigned To: @jwells131313

[glassfishrobot]

@glassfishrobot Commented Reported by cowwoc

[glassfishrobot]

@glassfishrobot Commented cowwoc said: My comment contains a typo: "the documentation doesn't mention of populating ..." should read "the documentation doesn't mention a way of populating ..."

[glassfishrobot]

@glassfishrobot Commented This issue was imported from java.net JIRA HK2-165