Many method descriptions have complicated and/or
mathematically-inclined descriptions that look more like proofs
of theorems than an API. In general mixing mathematical
notation with java notation is unacceptable, and mathematical
notation should not appear in descriptions having
nothing to do with advanced mathematics. See especially

java.naming.Name.html#compareTo(java.lang.Object)
java.naming.CompositeName.html#compareTo(java.lang.Object)
java.naming.CompooundName.html#compareTo(java.lang.Object)

Descriptions of these properties aid in helping the user
understand the operation of the method, but should be
explained using complete sentences.


Method java.naming.Name.compareTo(java.lang.Object) does not describe
HOW it is comparing an object or what results correspond to
which return values. It is possible to write an implementation
functioning exactly opposite of JavaSoft's implementation and
be able to claim it correctly implements the API. Needless
to say, calling functions of these alternate implementations
will no longer operate correctly.

brian.preston@eng 1997-10-23