Worst design and esp. documentation in Java???
801313Nov 8 2011 — edited Nov 10 2011I'm talking about javax.swing.undo.UndoableEdit
http://download.oracle.com/javase/7/docs/api/javax/swing/undo/UndoableEdit.html
From the javadoc:
... "UndoableEdit is designed to be used with the UndoManager. As UndoableEdits are generated by an UndoableEditListener they are typically added to the UndoManager." Why from an UndoableEditListener??? Couldn't this be from any source?
"If addEdit returns false replaceEdit is called on the new edit with the current edit passed in as the argument. This is the inverse of addEdit — if the new edit returns true from replaceEdit, the new edit replaces the current edit."
Huh? Am I the only one who had to read this 3 times to understand it?
"The UndoManager makes use of isSignificant to determine how many edits should be undone or redone. The UndoManager will undo or redo all insignificant edits (isSignificant returns false) between the current edit and the last or next significant edit. addEdit and replaceEdit can be used to treat multiple edits as a single edit, returning false from isSignificant allows for treating can be used to have many smaller edits undone or redone at once. Similar functionality can also be done using the addEdit method"
Does this not say the same thing twice? Also, there are grammatical problems around "allows for treating can be used to have many smaller edits undone or redone at once"
The designers admit that there are two ways to do the same thing with insignificant edits, but make no comments about why they made this design choice nor which is preferred under which set of circumstances. Why would you make more methods to support when they have the same functionality???
Where can I enter a bug / request for clarification for this?