Ensure JavaDoc and ScalaDoc is in good shape for all public APIs

[akara]

Need a thorough review of the APIs and make sure all is documented. Actor-based interaction would need different kind of documentation, which should be pursued differently.