https://issues.apache.org/jira/browse/HADOOP-6668
Check this out. This looks like a clean way to solve this issue in Mahout as well. If we annotate each package as public stable, private stable, public unstable, and so on and so forth, and keep only the stable ones in the javadoc, Users will find the documentations a lot more readable. Plus developers can keep adding experimental stuff with bad style as long as it is not marked visible. We can keep separate quality levels for each visibility. Mahout will always attract experimental code, so instead of driving it away and waiting for the quality to go up before committing, we can annotate it at the least quality level and when it improves, we can change the annotation along with the improvements. I can help creating a patch like this, if everyone is onboard Robin
