<AWT Dev> JDK 9 RFR of JDK-8033181: Fix doclint missing issues in java.awt.{peer, im[.spi]}

[Joe Darcy]

*ping*

Thanks,

-Joe

On 01/29/2014 11:23 AM, Joe Darcy wrote:
> Hello,
>
> Please review my proposed fix for
>
>     JDK-8033181: Fix doclint missing issues in java.awt.{peer, im[.spi]}
>
> Patch below; full webrev at
>
>     http://cr.openjdk.java.net/~darcy/8033181.0/
>
> Thanks,
>
> -Joe
>
> --- old/src/share/classes/java/awt/im/InputContext.java 2014-01-29 
> 11:17:17.000000000 -0800
> +++ new/src/share/classes/java/awt/im/InputContext.java 2014-01-29 
> 11:17:17.000000000 -0800
> @@ -1,5 +1,5 @@
>  /*
> - * Copyright (c) 1997, 2008, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights 
> reserved.
>   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>   *
>   * This code is free software; you can redistribute it and/or modify it
> @@ -87,6 +87,7 @@
>
>      /**
>       * Returns a new InputContext instance.
> +     * @return a new InputContext instance
>       */
>      public static InputContext getInstance() {
>          return new sun.awt.im.InputMethodContext();
> --- old/src/share/classes/java/awt/im/InputMethodHighlight.java 
> 2014-01-29 11:17:18.000000000 -0800
> +++ new/src/share/classes/java/awt/im/InputMethodHighlight.java 
> 2014-01-29 11:17:18.000000000 -0800
> @@ -1,5 +1,5 @@
>  /*
> - * Copyright (c) 1997, 2004, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights 
> reserved.
>   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>   *
>   * This code is free software; you can redistribute it and/or modify it
> @@ -157,6 +157,7 @@
>
>      /**
>       * Returns whether the text range is selected.
> +     * @return whether the text range is selected
>       */
>      public boolean isSelected() {
>          return selected;
> @@ -174,6 +175,7 @@
>
>      /**
>       * Returns the variation of the text range.
> +     * @return the variation of the text range
>       */
>      public int getVariation() {
>          return variation;
> @@ -181,6 +183,7 @@
>
>      /**
>       * Returns the rendering style attributes for the text range, or 
> null.
> +     * @return the rendering style attributes for the text range, or 
> null
>       * @since 1.3
>       */
>      public Map<TextAttribute,?> getStyle() {
> --- old/src/share/classes/java/awt/im/spi/InputMethodContext.java 
> 2014-01-29 11:17:19.000000000 -0800
> +++ new/src/share/classes/java/awt/im/spi/InputMethodContext.java 
> 2014-01-29 11:17:18.000000000 -0800
> @@ -1,5 +1,5 @@
>  /*
> - * Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights 
> reserved.
>   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>   *
>   * This code is free software; you can redistribute it and/or modify it
> @@ -52,6 +52,14 @@
>       * Creates an input method event from the arguments given
>       * and dispatches it to the client component. For arguments,
>       * see {@link java.awt.event.InputMethodEvent#InputMethodEvent}.
> +     * @param id the event type
> +     * @param text the combined committed and composed text
> +     * @param committedCharacterCount the number of committed 
> characters in the text
> +     * @param caret the caret (a.k.a. insertion point); null if
> +     * there's no caret within current composed text
> +     * @param visiblePosition the position that's most important to be
> +     * visible; null if there's no recommendation for a visible
> +     * position within current composed text
>       */
>      public void dispatchInputMethodEvent(int id,
>                  AttributedCharacterIterator text, int 
> committedCharacterCount,
> --- old/src/share/classes/java/awt/im/spi/InputMethodDescriptor.java 
> 2014-01-29 11:17:19.000000000 -0800
> +++ new/src/share/classes/java/awt/im/spi/InputMethodDescriptor.java 
> 2014-01-29 11:17:19.000000000 -0800
> @@ -1,5 +1,5 @@
>  /*
> - * Copyright (c) 1998, 1999, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights 
> reserved.
>   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>   *
>   * This code is free software; you can redistribute it and/or modify it
> @@ -72,6 +72,8 @@
>       * Returns whether the list of available locales can change
>       * at runtime. This may be the case, for example, for adapters
>       * that access real input methods over the network.
> +     * @return whether the list of available locales can change at
> +     * runtime
>       */
>      boolean hasDynamicLocaleList();
>
> @@ -92,6 +94,9 @@
>       *
>       * @param inputLocale the locale for which text input is 
> supported, or null
>       * @param displayLanguage the language in which the name will be 
> displayed
> +     * @return the user-visible name of the corresponding input method
> +     * for the given input locale in the language in which the name
> +     * will be displayed
>       */
>      String getInputMethodDisplayName(Locale inputLocale, Locale 
> displayLanguage);
>
> --- old/src/share/classes/java/awt/peer/CanvasPeer.java 2014-01-29 
> 11:17:20.000000000 -0800
> +++ new/src/share/classes/java/awt/peer/CanvasPeer.java 2014-01-29 
> 11:17:20.000000000 -0800
> @@ -1,5 +1,5 @@
>  /*
> - * Copyright (c) 1995, 2007, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. All rights 
> reserved.
>   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>   *
>   * This code is free software; you can redistribute it and/or modify it
> @@ -42,6 +42,8 @@
>       * from the requested GC passed as the argument to this method. 
> This method
>       * must return a non-null value (given the argument is non-null 
> as well).
>       *
> +     * @param gc the requested graphics configuration
> +     * @return a graphics configuration that best suits this Canvas
>       * @since 1.7
>       */
>      GraphicsConfiguration getAppropriateGraphicsConfiguration(
> --- old/src/share/classes/java/awt/peer/ComponentPeer.java 2014-01-29 
> 11:17:20.000000000 -0800
> +++ new/src/share/classes/java/awt/peer/ComponentPeer.java 2014-01-29 
> 11:17:20.000000000 -0800
> @@ -1,5 +1,5 @@
>  /*
> - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. All rights 
> reserved.
>   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>   *
>   * This code is free software; you can redistribute it and/or modify it
> @@ -516,6 +516,7 @@
>
>      /**
>       * Applies the shape to the native component window.
> +     * @param shape the shape to apply
>       * @since 1.7
>       *
>       * @see Component#applyCompoundShape
> @@ -525,12 +526,13 @@
>      /**
>       * Lowers this component at the bottom of the above HW peer. If 
> the above parameter
>       * is null then the method places this component at the top of 
> the Z-order.
> +     * @param above the peer to lower this component with respect to
>       */
>      void setZOrder(ComponentPeer above);
>
>      /**
>       * Updates internal data structures related to the component's GC.
> -     *
> +     * @param gc the reference graphics configuration
>       * @return if the peer needs to be recreated for the changes to 
> take effect
>       * @since 1.7
>       */
> --- old/src/share/classes/java/awt/peer/MouseInfoPeer.java 2014-01-29 
> 11:17:21.000000000 -0800
> +++ new/src/share/classes/java/awt/peer/MouseInfoPeer.java 2014-01-29 
> 11:17:21.000000000 -0800
> @@ -1,5 +1,5 @@
>  /*
> - * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights 
> reserved.
>   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>   *
>   * This code is free software; you can redistribute it and/or modify it
> @@ -55,6 +55,10 @@
>       * is located.
>       * See java.awt.GraphicsConfiguration documentation for more
>       * details about virtual screen devices.
> +     * @param point holder for the current coordinates of the mouse
> +     * cursor
> +     * @return the number of the screen device where the pointer is
> +     * located
>       */
>      int fillPointWithCoords(Point point);
>
> @@ -63,6 +67,9 @@
>       * pointer. The window is considered to be under the mouse pointer
>       * if it is showing on the screen, and the mouse pointer is above
>       * the part of the window that is not obscured by any other windows.
> +     * @param w the window to check
> +     * @return whether or not the window is located under the mouse
> +     * pointer
>       */
>      boolean isWindowUnderMouse(Window w);
>
> --- old/src/share/classes/java/awt/peer/WindowPeer.java 2014-01-29 
> 11:17:22.000000000 -0800
> +++ new/src/share/classes/java/awt/peer/WindowPeer.java 2014-01-29 
> 11:17:22.000000000 -0800
> @@ -1,5 +1,5 @@
>  /*
> - * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights 
> reserved.
> + * Copyright (c) 1995, 2014, Oracle and/or its affiliates. All rights 
> reserved.
>   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>   *
>   * This code is free software; you can redistribute it and/or modify it
> @@ -94,14 +94,15 @@
>
>      /**
>       * Sets the level of opacity for the window.
> -     *
> +     * @param opacity the level of opacity
>       * @see Window#setOpacity(float)
>       */
>      void setOpacity(float opacity);
>
>      /**
>       * Enables the per-pixel alpha support for the window.
> -     *
> +     * @param isOpaque whether or not per-pixel alpha support is
> +     * enabled
>       * @see Window#setBackground(Color)
>       */
>      void setOpaque(boolean isOpaque);
>