8033181: Fix doclint missing issues in java.awt.{peer, im[.spi]}

Reviewed-by: alanb

jdk/src/share/classes/java/awt/im/InputContext.java

@@ -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 @@ public class InputContext {
 
     /**
      * Returns a new InputContext instance.
+     * @return a new InputContext instance
      */
     public static InputContext getInstance() {
         return new sun.awt.im.InputMethodContext();

jdk/src/share/classes/java/awt/im/InputMethodHighlight.java

@@ -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 @@ public class InputMethodHighlight {
 
     /**
      * Returns whether the text range is selected.
+     * @return whether the text range is selected
      */
     public boolean isSelected() {
         return selected;
@@ -174,6 +175,7 @@ public class InputMethodHighlight {
 
     /**
      * Returns the variation of the text range.
+     * @return the variation of the text range
      */
     public int getVariation() {
         return variation;
@@ -181,6 +183,7 @@ public class InputMethodHighlight {
 
     /**
      * 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() {

jdk/src/share/classes/java/awt/im/spi/InputMethodContext.java

@@ -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 @@ public interface InputMethodContext extends InputMethodRequests {
      * 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,

jdk/src/share/classes/java/awt/im/spi/InputMethodDescriptor.java

@@ -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 @@ public interface InputMethodDescriptor {
      * 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 @@ public interface InputMethodDescriptor {
      *
      * @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);
 

jdk/src/share/classes/java/awt/peer/CanvasPeer.java

@@ -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 @@ public interface CanvasPeer extends ComponentPeer {
      * 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(

jdk/src/share/classes/java/awt/peer/ComponentPeer.java

@@ -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 @@ public interface ComponentPeer {
 
     /**
      * Applies the shape to the native component window.
+     * @param shape the shape to apply
      * @since 1.7
      *
      * @see Component#applyCompoundShape
@@ -525,12 +526,13 @@ public interface ComponentPeer {
     /**
      * 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
      */

jdk/src/share/classes/java/awt/peer/MouseInfoPeer.java

@@ -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 @@ public interface MouseInfoPeer {
      * 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 @@ public interface MouseInfoPeer {
      * 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);
 

jdk/src/share/classes/java/awt/peer/WindowPeer.java

@@ -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 @@ public interface WindowPeer extends ContainerPeer {
 
     /**
      * 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);