7121905: grammatically incorrect apostrophe in BeanInfo javadoc

Reviewed-by: rupashka

src/share/classes/java/beans/BeanInfo.java

 /*
- * Copyright (c) 1996, 1999, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2012, 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
@@ -25,134 +25,134 @@
 
 package java.beans;
 
+import java.awt.Image;
+
 /**
- * A bean implementor who wishes to provide explicit information about
- * their bean may provide a BeanInfo class that implements this BeanInfo
- * interface and provides explicit information about the methods,
- * properties, events, etc, of their  bean.
+ * Use the {@code BeanInfo} interface
+ * to create a {@code BeanInfo} class
+ * and provide explicit information about the methods,
+ * properties, events, and other features of your beans.
  * <p>
- * A bean implementor doesn't need to provide a complete set of
- * explicit information.  You can pick and choose which information
- * you want to provide and the rest will be obtained by automatic
- * analysis using low-level reflection of the bean classes' methods
+ * When developing your bean, you can implement
+ * the bean features required for your application task
+ * omitting the rest of the {@code BeanInfo} features.
+ * They will be obtained through the automatic analysis
+ * by using the low-level reflection of the bean methods
  * and applying standard design patterns.
+ * You have an opportunity to provide additional bean information
+ * through various descriptor classes.
+ * <p>
+ * See the {@link SimpleBeanInfo} class that is
+ * a convenient basic class for {@code BeanInfo} classes.
+ * You can override the methods and properties of
+ * the {@code SimpleBeanInfo} class to define specific information.
  * <p>
- * You get the opportunity to provide lots and lots of different
- * information as part of the various XyZDescriptor classes.  But
- * don't panic, you only really need to provide the minimal core
- * information required by the various constructors.
- * <P>
- * See also the SimpleBeanInfo class which provides a convenient
- * "noop" base class for BeanInfo classes, which you can override
- * for those specific places where you want to return explicit info.
- * <P>
- * To learn about all the behaviour of a bean see the Introspector class.
+ * See also the {@link Introspector} class to learn more about bean behavior.
  */
-
 public interface BeanInfo {
 
     /**
-     * Gets the beans <code>BeanDescriptor</code>.
+     * Returns the bean descriptor
+     * that provides overall information about the bean,
+     * such as its display name or its customizer.
      *
-     * @return  A BeanDescriptor providing overall information about
-     * the bean, such as its displayName, its customizer, etc.  May
-     * return null if the information should be obtained by automatic
-     * analysis.
+     * @return  a {@link BeanDescriptor} object,
+     *          or {@code null} if the information is to
+     *          be obtained through the automatic analysis
      */
     BeanDescriptor getBeanDescriptor();
 
     /**
-     * Gets the beans <code>EventSetDescriptor</code>s.
+     * Returns the event descriptors of the bean
+     * that define the types of events fired by this bean.
      *
-     * @return  An array of EventSetDescriptors describing the kinds of
-     * events fired by this bean.  May return null if the information
-     * should be obtained by automatic analysis.
+     * @return  an array of {@link EventSetDescriptor} objects,
+     *          or {@code null} if the information is to
+     *          be obtained through the automatic analysis
      */
     EventSetDescriptor[] getEventSetDescriptors();
 
     /**
-     * A bean may have a "default" event that is the event that will
-     * mostly commonly be used by humans when using the bean.
-     * @return Index of default event in the EventSetDescriptor array
-     *          returned by getEventSetDescriptors.
-     * <P>      Returns -1 if there is no default event.
+     * A bean may have a default event typically applied when this bean is used.
+     *
+     * @return  index of the default event in the {@code EventSetDescriptor} array
+     *          returned by the {@code getEventSetDescriptors} method,
+     *          or -1 if there is no default event
      */
     int getDefaultEventIndex();
 
     /**
      * Returns descriptors for all properties of the bean.
-     * May return {@code null} if the information
-     * should be obtained by automatic analysis.
      * <p>
      * If a property is indexed, then its entry in the result array
-     * will belong to the {@link IndexedPropertyDescriptor} subclass
+     * belongs to the {@link IndexedPropertyDescriptor} subclass
      * of the {@link PropertyDescriptor} class.
      * A client of the {@code getPropertyDescriptors} method
-     * can use "{@code instanceof}" to check
+     * can use the {@code instanceof} operator to check
      * whether a given {@code PropertyDescriptor}
      * is an {@code IndexedPropertyDescriptor}.
      *
-     * @return an array of {@code PropertyDescriptor}s
-     *         describing all properties supported by the bean
-     *         or {@code null}
+     * @return  an array of {@code PropertyDescriptor} objects,
+     *          or {@code null} if the information is to
+     *          be obtained through the automatic analysis
      */
     PropertyDescriptor[] getPropertyDescriptors();
 
     /**
-     * A bean may have a "default" property that is the property that will
-     * mostly commonly be initially chosen for update by human's who are
-     * customizing the bean.
-     * @return  Index of default property in the PropertyDescriptor array
-     *          returned by getPropertyDescriptors.
-     * <P>      Returns -1 if there is no default property.
+     * A bean may have a default property commonly updated when this bean is customized.
+     *
+     * @return  index of the default property in the {@code PropertyDescriptor} array
+     *          returned by the {@code getPropertyDescriptors} method,
+     *          or -1 if there is no default property
      */
     int getDefaultPropertyIndex();
 
     /**
-     * Gets the beans <code>MethodDescriptor</code>s.
+     * Returns the method descriptors of the bean
+     * that define the externally visible methods supported by this bean.
      *
-     * @return An array of MethodDescriptors describing the externally
-     * visible methods supported by this bean.  May return null if
-     * the information should be obtained by automatic analysis.
+     * @return  an array of {@link MethodDescriptor} objects,
+     *          or {@code null} if the information is to
+     *          be obtained through the automatic analysis
      */
     MethodDescriptor[] getMethodDescriptors();
 
     /**
-     * This method allows a BeanInfo object to return an arbitrary collection
-     * of other BeanInfo objects that provide additional information on the
-     * current bean.
-     * <P>
-     * If there are conflicts or overlaps between the information provided
-     * by different BeanInfo objects, then the current BeanInfo takes precedence
-     * over the getAdditionalBeanInfo objects, and later elements in the array
-     * take precedence over earlier ones.
+     * This method enables the current {@code BeanInfo} object
+     * to return an arbitrary collection of other {@code BeanInfo} objects
+     * that provide additional information about the current bean.
+     * <p>
+     * If there are conflicts or overlaps between the information
+     * provided by different {@code BeanInfo} objects,
+     * the current {@code BeanInfo} object takes priority
+     * over the additional {@code BeanInfo} objects.
+     * Array elements with higher indices take priority
+     * over the elements with lower indices.
      *
-     * @return an array of BeanInfo objects.  May return null.
+     * @return  an array of {@code BeanInfo} objects,
+     *          or {@code null} if there are no additional {@code BeanInfo} objects
      */
     BeanInfo[] getAdditionalBeanInfo();
 
     /**
-     * This method returns an image object that can be used to
-     * represent the bean in toolboxes, toolbars, etc.   Icon images
-     * will typically be GIFs, but may in future include other formats.
-     * <p>
-     * Beans aren't required to provide icons and may return null from
-     * this method.
+     * Returns an image that can be used to represent the bean in toolboxes or toolbars.
      * <p>
-     * There are four possible flavors of icons (16x16 color,
-     * 32x32 color, 16x16 mono, 32x32 mono).  If a bean choses to only
-     * support a single icon we recommend supporting 16x16 color.
-     * <p>
-     * We recommend that icons have a "transparent" background
-     * so they can be rendered onto an existing background.
+     * There are four possible types of icons:
+     * 16 x 16 color, 32 x 32 color, 16 x 16 mono, and 32 x 32 mono.
+     * If you implement a bean so that it supports a single icon,
+     * it is recommended to use 16 x 16 color.
+     * Another recommendation is to set a transparent background for the icons.
+     *
+     * @param  iconKind  the kind of icon requested
+     * @return           an image object representing the requested icon,
+     *                   or {@code null} if no suitable icon is available
      *
-     * @param  iconKind  The kind of icon requested.  This should be
-     *    one of the constant values ICON_COLOR_16x16, ICON_COLOR_32x32,
-     *    ICON_MONO_16x16, or ICON_MONO_32x32.
-     * @return  An image object representing the requested icon.  May
-     *    return null if no suitable icon is available.
+     * @see #ICON_COLOR_16x16
+     * @see #ICON_COLOR_32x32
+     * @see #ICON_MONO_16x16
+     * @see #ICON_MONO_32x32
      */
-    java.awt.Image getIcon(int iconKind);
+    Image getIcon(int iconKind);
 
     /**
      * Constant to indicate a 16 x 16 color icon.