Códigos Mentirosos

Já faz um tempo, eu dou uma olhada nos códigos do JDK, e percebo algumas coisas bem mentirosas, que as vezes me deixam confuso ou indignado.

Não que o código seja mentira, mas pelo menos a documentação é

vou postar alguns exemplos, e vocês me dizem o que acham

java.awt.event.KeyEvent

/**
* This constant is obsolete, and is included only for backwards
* compatibility.
* @see #VK_SEPARATOR
*/

 public static final int VK_SEPARATER = 0x6C;

 /**
 * Constant for the Numpad Separator key.
 * @since 1.4
 */
 public static final int VK_SEPARATOR = VK_SEPARATER;

Porque o primeiro é obsoleto se ele é igual ao segundo??

java.awt.Component

/**
* Transfers the focus to the next component, as though this Component were
* the focus owner.
* @see #requestFocus()
* @since JDK1.1
*/
public void transferFocus() {

 nextFocus();
 }

 /**
 * @deprecated As of JDK version 1.1,
 * replaced by transferFocus().
 */
 @Deprecated
 public void nextFocus() {
 transferFocus(false);
 }

nextFocus() é obsoleto, deve ser substituido por transferFocus().

Mas, transferFocus simplesmente chama nextFocus!!!!

porque eu não devo usar, se ele mesmo usa?

java.awt.Component (de novo!)

/**
* Shows or hides this component depending on the value of parameter

 * <code>b</code>.
 * <p>
 * This method changes layout-related information, and therefore,
 * invalidates the component hierarchy.
 *
 * @param b if <code>true</code>, shows this component;
 * otherwise, hides this component
 * @see #isVisible
 * @see #invalidate
 * @since JDK1.1
 */
 public void setVisible(boolean B) {
 show(B);
 }

/**
* @deprecated As of JDK version 1.1,

 * replaced by <code>setVisible(boolean)</code>.
 */
 @Deprecated
 public void show() {
 //[...]
 }

/**
* @deprecated As of JDK version 1.1,

 * replaced by <code>setVisible(boolean)</code>.
 */
 @Deprecated
 public void show(boolean B) {
 if (B) {
 show();
 } else {
 hide();
 }
 }

/**
* @deprecated As of JDK version 1.1,

 * replaced by <code>setVisible(boolean)</code>.
 */
 @Deprecated
 public void hide() {
 //[...]
 }

Todo mundo sabe que não se deve usar o show() ou hide(), ou show(boolean), se usa o setVisible(boolean) no lugar.

Por que mesmo??????

java.lang.Thread

Essa foi a primeira que me deixou indignado

/**
* Causes the currently executing thread to sleep (temporarily cease
* execution) for the specified number of milliseconds, subject to
* the precision and accuracy of system timers and schedulers. The thread
* does not lose ownership of any monitors.
*
* @param millis
* the length of time to sleep in milliseconds
*
* @throws IllegalArgumentException
* if the value of {@code millis} is negative
*
* @throws InterruptedException
* if any thread has interrupted the current thread. The

 * <i>interrupted status</i> of the current thread is
 * cleared when this exception is thrown.
 */
 public static native void sleep(long millis) throws InterruptedException;

 /**
 * Causes the currently executing thread to sleep (temporarily cease
 * execution) for the specified number of milliseconds plus the specified
 * number of nanoseconds, subject to the precision and accuracy of system
 * timers and schedulers. The thread does not lose ownership of any
 * monitors.
 *
 * @param millis
 * the length of time to sleep in milliseconds
 *
 * @param nanos
 * {@code 0-999999} additional nanoseconds to sleep
 *
 * @throws IllegalArgumentException
 * if the value of {@code millis} is negative, or the value of
 * {@code nanos} is not in the range {@code 0-999999}
 *
 * @throws InterruptedException
 * if any thread has interrupted the current thread. The
 * <i>interrupted status</i> of the current thread is
 * cleared when this exception is thrown.
 */
 public static void sleep(long millis, int nanos)
 throws InterruptedException {
 if (millis < 0) {
 throw new IllegalArgumentException("timeout value is negative");
 }

 if (nanos < 0 || nanos > 999999) {
 throw new IllegalArgumentException(
 "nanosecond timeout value out of range");
 }

 if (nanos >= 500000 || (nanos != 0 && millis == 0)) {
 millis++;
 }

 sleep(millis);
 }

 

 sleep(long millis, int nanos), diz que interrompe por milissegundos mais nanosegundos, mas na verdade, ele só faz uma verificação muito inteligente, e depois incrementa (ou não) um milisegundo a mais.

E ainda quer botar a culpa no sistema, dizendo

>
subject to the precision and accuracy of system

timers and schedulers.

esse me deixou muito indignado.