base

bug:3474580 fix javadoc

of all the solutions, fixing the javadoc seems like the most useful thing to do
on this otherwise confusing API.

Change-Id: I1fb438c1dd21c5a5f6805db277e6a3f119cdd6ce