I have copied the interface classification stuff from HADOOP-5073 in the attached html.
I plan to add this Overview.html in the package o.a.h.classification.
I have added a couple of FAQs and minor edits but the text is mostly unchanged from HADOOP-5073

Update document

Also: @VisibleForTesting, "this is for testing only; you should not be using this at all except while writing unit tests for the specific Hadoop project". Package-scoped classes and methods often also used for this purpose.

Uploading a patch that copies Sanjay's html file to apt.vm format verbatim.

The patches do a brilliant job of summarizing the discussion on HADOOP-5073.

I have a few minor comments on the patch that I intend to incorporate in the next version:

1. Move the sections around a little bit. e.g. FAQ should probably be towards the end
2. As this is specific to Hadoop, may be we need not mention company-private as a bullet, but may be can include a note on it later in the text.
3. Few other cosmetic changes.

Updated patch with the changes mentioned above. The content is almost identical to the previous patch.

Sanjay Radia, please feel free to revert my changes as you see fit. Just thought it might be simpler to put them in there.

Need to address one more point:

APIs of private audience will not be part of the public javadoc generated by ant (i.e. by the mvn target javadoc:javadoc); they will only be generated for the developer javadoc (generated by ant target "javadoc-dev")

I am not aware of a way to generate dev-specific javadoc using mvn.

Including a blurb on APIs with VisibleForTesting.

Updated patch addresses javadoc. I believe this is ready for review.

-1 overall. Here are the results of testing the latest attachment
http://issues.apache.org/jira/secure/attachment/12585267/hadoop-7391-v3.patch
against trunk revision .

+1 @author. The patch does not contain any @author tags.

-1 tests included. The patch doesn't appear to include any new or modified tests.
Please justify why no new tests are needed for this patch.
Also please list what manual steps were performed to verify this patch.

+1 javac. The applied patch does not increase the total number of javac compiler warnings.

+1 javadoc. The javadoc tool did not generate any warning messages.

+1 eclipse:eclipse. The patch built with eclipse:eclipse.

+1 findbugs. The patch does not introduce any new Findbugs (version 1.3.9) warnings.

+1 release audit. The applied patch does not increase the total number of release audit warnings.

+1 core tests. The patch passed unit tests in hadoop-common-project/hadoop-common.

+1 contrib tests. The patch passed contrib unit tests.

Test results: https://builds.apache.org/job/PreCommit-HADOOP-Build/2579//testReport/
Console output: https://builds.apache.org/job/PreCommit-HADOOP-Build/2579//console

This message is automatically generated.

+1 to both the HTML and apt format documentation from my side.

Thanks for converting the format; like the minor changes you made.
Attaching an updated patch with one more FAQ that came up yesterday in some discussions.

+1 to the latest changes as well.

-1 overall. Here are the results of testing the latest attachment
http://issues.apache.org/jira/secure/attachment/12585433/hadoop-7391-v4.patch
against trunk revision .

+1 @author. The patch does not contain any @author tags.

-1 tests included. The patch doesn't appear to include any new or modified tests.
Please justify why no new tests are needed for this patch.
Also please list what manual steps were performed to verify this patch.

+1 javac. The applied patch does not increase the total number of javac compiler warnings.

+1 javadoc. The javadoc tool did not generate any warning messages.

+1 eclipse:eclipse. The patch built with eclipse:eclipse.

+1 findbugs. The patch does not introduce any new Findbugs (version 1.3.9) warnings.

+1 release audit. The applied patch does not increase the total number of release audit warnings.

+1 core tests. The patch passed unit tests in hadoop-common-project/hadoop-common.

+1 contrib tests. The patch passed contrib unit tests.

Test results: https://builds.apache.org/job/PreCommit-HADOOP-Build/2587//testReport/
Console output: https://builds.apache.org/job/PreCommit-HADOOP-Build/2587//console

This message is automatically generated.

Integrated in Hadoop-trunk-Commit #3817 (See https://builds.apache.org/job/Hadoop-trunk-Commit/3817/)
HADOOP-7391 Document Interface Classification from HADOOP-5073 (sanjay Radia) (Revision 1488069)

Result = SUCCESS
sradia : http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1488069
Files :

• /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt
• /hadoop/common/trunk/hadoop-common-project/hadoop-common/src/site/apt/InterfaceClassification.apt.vm

Committed to trunk and merged to branch2.

Integrated in Hadoop-Yarn-trunk #226 (See https://builds.apache.org/job/Hadoop-Yarn-trunk/226/)
HADOOP-7391 Document Interface Classification from HADOOP-5073 (sanjay Radia) (Revision 1488069)

Result = SUCCESS
sradia : http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1488069
Files :

• /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt
• /hadoop/common/trunk/hadoop-common-project/hadoop-common/src/site/apt/InterfaceClassification.apt.vm

Integrated in Hadoop-Hdfs-trunk #1416 (See https://builds.apache.org/job/Hadoop-Hdfs-trunk/1416/)
HADOOP-7391 Document Interface Classification from HADOOP-5073 (sanjay Radia) (Revision 1488069)

Result = FAILURE
sradia : http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1488069
Files :

• /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt
• /hadoop/common/trunk/hadoop-common-project/hadoop-common/src/site/apt/InterfaceClassification.apt.vm

Integrated in Hadoop-Mapreduce-trunk #1442 (See https://builds.apache.org/job/Hadoop-Mapreduce-trunk/1442/)
HADOOP-7391 Document Interface Classification from HADOOP-5073 (sanjay Radia) (Revision 1488069)

Result = SUCCESS
sradia : http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1488069
Files :

• /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt
• /hadoop/common/trunk/hadoop-common-project/hadoop-common/src/site/apt/InterfaceClassification.apt.vm