Your idea sound good. Better java docs are always good and never enough.
Sent from my iPhone On Oct 22, 2012, at 12:59 PM, Timothy Mann <[email protected]> wrote: > Yes, I understand. Interfaces are almost impossible to get right the first > time and equally impossible to change once they have been made public. My > interest is in improving the javadoc to help point new users in the right > direction. I was thinking about adding a note in the description of > AbstractVectorClassifier that simply emphasizes the importance of > classifyFull as a starting place. > > I also plan on adding javadoc comments to methods where classify throws an > UnsupportedOperationException to indicate this instead of allowing default > copying of the superclass javadoc comment (which does not indicate that the > method is unsupported). > > Any other ideas? > > -Timothy Mann > > On Sun, Oct 21, 2012 at 11:20 PM, Ted Dunning <[email protected]> wrote: > >> Yes. >> >> It seems stupid in retrospect. Changing these things is very painful, >> however, because we have no idea how many people will be affected. >> >> On Sun, Oct 21, 2012 at 9:16 PM, Timothy Mann <[email protected] >>> wrote: >> >>> It seems strange to me that the classify method declared in >>> AbstractVectorClassifier returns a vector with n-1 scores, where n is the >>> number of categories. I understand that this decision was made for >>> efficiency reasons, but it seems like classify is the first place where >>> people will look in the API. Instead classifyFull provides the >>> implementation that a user may find more intuitive. Furthermore, >>> classifyFull does not require the assumption that the scores over all >>> categories represent probabilities that sum to one, and is therefore more >>> general. In fact, classify is not even implemented for the Naive Bayes >>> implementations but classifyFull is, which was initially confusing until >> I >>> understood what classify actually does. Any thoughts on this? >>> >>> -Timothy Mann >>> >>
