The Javadoc really needs some love. I fully realize that you didn't write most of the existing Javadoc but, nonetheless, it needs to be fixed. It's crucial.
Please go through all of the Javadoc for the all Api classes and all domain objects with a fine toothed comb. Here's what needs to be fixed. - [ ] Remove all @see links from the Javadoc (Developers should not be taken out of their dev env to some website in order to understand how a method works. Also the raw API docs are likely to be confusing to a Java dev.) - [ ] Copying the content from the API docs is okay but it needs to be edited so it makes sense to a Java dev. Look at it from the perspective of someone who knows Java but might not know much (if anything) about the cloud. - [ ] For domain objects that a dev creates (e.g. SwiftObject), all comments should be on the builder methods. That way when they're using an IDE the Javadoc that pops up is helpful. - [ ] For domain objects that are solely created by responses (e.g. BulkDeleteResponse), all comments should just be on the object get methods. --- Reply to this email directly or view it on GitHub: https://github.com/jclouds/jclouds-labs-openstack/pull/79#issuecomment-36366230
