Use accessors instead of public variable
Update JavaDoc

This change removes misformatted comments and adds detailed explanation of the
changes made in
0806d525e28981f57829974eed649829060e59bd#diff-9e2bfafed49fac06409472e04d8b1592R239