Document module classes

[lucidd]

The module classes and functions have not been documented so far since they are only bindings to the salt module functions and the documentation already exists there. Furthermore our library may work with different salt versions which could have slightly different but documented behavior. In that case our documentation would never be correct since it always depends against which salt version you run it.

One suggestion by @isbm is to provide links in the documentation of each function/module to the latest documentation on the salt side. That wouldn't be always correct but from there its easy to switch to the documentation of a different version.

[AdamMajer]

Providing a link to latest external documentation is OK, but for SUSE these should probably be transformed to file:// links in salt-doc package. The later can be done with a small script that transforms and validates links before javadoc is generated. Hopefully nothing more than sed and tiny bash script is needed here.

One sentence description of what each function/class does should be included as well. Bare links look bad.

[isbm]

On top of Oracle's guide for Javadoc my reasoning is that additionally:

• It is not handy to code with this library and IDE does not show any quick docs at all.
• Having no docs at all seems like something is not finished.
• Usually all typical bindings, say to ZMQ via JNI, also have docstrings. Even JAXB to the webservices does this.
• It is not exact bindings anyway and may differ from version to version!
• It helps when javadoc at least helps you to grasp what it is and where to look for further info.

Therefore I suggest to keep the following format to all binded methods:

/**
 * This stuff does this and that.
 * (Generic copypaste from the Salt documentation, likely license is OK with this)
 *
 * @param tgt This Gooey Thing
 * @param lots_of_stuff Who knows what
 *
 * @return always null to make you mad
 *
 * @since 2015.8 Beryllium
 * @see <a href="http://docs.saltstack.com/latest/module#exact_section">module.name</a>
/*

Please note, that we should write generic description and give a URL to the current version of the API. So the developer with the precise version will switch to it.