17ed60c3d2
Cf conversation with the API council. Also expand the javadoc a bit. Change-Id: I9d4edb1042e00492b3db5c6bb7c7d9648581efad