Fix documentation errors

Fix typos.
Fix javadoc error.
Fix wrong instructions about new returning null.

Change-Id: I76bca22e386839007fc99667b07649a4ced4180f

core/java/android/os/IBinder.java

@@ -162,7 +162,7 @@ public interface IBinder {
      * @param code The action to perform.  This should
      * be a number between {@link #FIRST_CALL_TRANSACTION} and
      * {@link #LAST_CALL_TRANSACTION}.
-     * @param data Marshalled data to send to the target.  Most not be null.
+     * @param data Marshalled data to send to the target.  Must not be null.
      * If you are not sending any data, you must create an empty Parcel
      * that is given here.
      * @param reply Marshalled data to be received from the target.  May be

core/java/android/view/Surface.java

@@ -24,7 +24,7 @@ import android.util.DisplayMetrics;
 import android.util.Log;
 
 /**
- * Handle on to a raw buffer that is being managed by the screen compositor.
+ * Handle onto a raw buffer that is being managed by the screen compositor.
  */
 public class Surface implements Parcelable {
     private static final String LOG_TAG = "Surface";
@@ -41,7 +41,7 @@ public class Surface implements Parcelable {
     @Deprecated
     public static final int HARDWARE            = 0x00000010;
 
-    /** Implies "HARDWARE", the surface is to be used by the GPU
+    /** Implies "HARDWARE", the surface is to be used by the GPU;
      * additionally the backbuffer is never preserved for these
      * surfaces. 
      * @deprecated this is ignored, this value is set automatically when needed.
@@ -81,9 +81,9 @@ public class Surface implements Parcelable {
     
     /**
      * Creates a surface without a rendering buffer. Instead, the content
-     * of the surface must be pushed by an external entity. This is type
+     * of the surface must be pushed by an external entity. This type
      * of surface can be used for efficient camera preview or movie
-     * play back.
+     * playback.
      *
      * @deprecated not support by the system anymore
      */
@@ -99,7 +99,7 @@ public class Surface implements Parcelable {
      */
     public static final int OPAQUE              = 0x00000400;
     
-    /** Creates a normal surface. This is the default */
+    /** Creates a normal surface. This is the default. */
     public static final int FX_SURFACE_NORMAL   = 0x00000000;
     
     /** Creates a Blur surface. Everything behind this surface is blurred
@@ -111,7 +111,7 @@ public class Surface implements Parcelable {
     public static final int FX_SURFACE_BLUR     = 0x00010000;
     
     /** Creates a Dim surface. Everything behind this surface is dimmed
-     * by the amount specified in setAlpha(). 
+     * by the amount specified in {@link #setAlpha}.
      * It is an error to lock a Dim surface, since it doesn't have
      * a backing store.
      */
@@ -122,14 +122,14 @@ public class Surface implements Parcelable {
 
     /* flags used with setFlags() (keep in sync with ISurfaceComposer.h) */
     
-    /** Hide the surface. Equivalent to calling hide() */
+    /** Hide the surface. Equivalent to calling hide(). */
     public static final int SURFACE_HIDDEN    = 0x01;
     
-    /** Freeze the surface. Equivalent to calling freeze() */ 
+    /** Freeze the surface. Equivalent to calling freeze(). */
     public static final int SURFACE_FROZEN     = 0x02;
 
     /**
-     * @deprecated use {@link #SURFACE_FROZEN} instead.
+     * @deprecated Use {@link #SURFACE_FROZEN} instead.
      */
     @Deprecated
     public static final int SURACE_FROZEN     = 0x02;
@@ -241,7 +241,7 @@ public class Surface implements Parcelable {
      *  like obtained from getMatrix. This is a hack to handle the case that an application
      *  uses getMatrix to keep the original matrix, set matrix of its own, then set the original
      *  matrix back. There is no perfect solution that works for all cases, and there are a lot of
-     *  cases that this model dose not work, but we hope this works for many apps.
+     *  cases that this model does not work, but we hope this works for many apps.
      * </ul>
      */
     private class CompatibleCanvas extends Canvas {
@@ -284,7 +284,7 @@ public class Surface implements Parcelable {
     }
 
     /**
-     * Sets the display metrics used to provide canva's width/height in compatibility mode.
+     * Sets the display metrics used to provide canvas's width/height in compatibility mode.
      */
     void setCompatibleDisplayMetrics(DisplayMetrics metrics, Translator translator) {
         mCompatibleDisplayMetrics = metrics;

core/java/android/view/SurfaceHolder.java

@@ -25,9 +25,10 @@ import android.graphics.Rect;
  * monitor changes to the surface.  This interface is typically available
  * through the {@link SurfaceView} class.
  * 
- * <p>When using this interface from a thread different than the one running
+ * <p>When using this interface from a thread other than the one running
  * its {@link SurfaceView}, you will want to carefully read the
- * {@link #lockCanvas} and {@link Callback#surfaceCreated Callback.surfaceCreated}.
+ * methods
+ * {@link #lockCanvas} and {@link Callback#surfaceCreated Callback.surfaceCreated()}.
  */
 public interface SurfaceHolder {
 
@@ -46,7 +47,7 @@ public interface SurfaceHolder {
 
     /**
      * Exception that is thrown from {@link #lockCanvas} when called on a Surface
-     * whose is SURFACE_TYPE_PUSH_BUFFERS.
+     * whose type is SURFACE_TYPE_PUSH_BUFFERS.
      */
     public static class BadSurfaceTypeException extends RuntimeException {
         public BadSurfaceTypeException() {
@@ -62,7 +63,7 @@ public interface SurfaceHolder {
      * changes to the surface.  When used with a {@link SurfaceView}, the
      * Surface being held is only available between calls to
      * {@link #surfaceCreated(SurfaceHolder)} and
-     * {@link #surfaceDestroyed(SurfaceHolder).  The Callback is set with
+     * {@link #surfaceDestroyed(SurfaceHolder)}.  The Callback is set with
      * {@link SurfaceHolder#addCallback SurfaceHolder.addCallback} method.
      */
     public interface Callback {
@@ -110,7 +111,7 @@ public interface SurfaceHolder {
         /**
          * Called when the application needs to redraw the content of its
          * surface, after it is resized or for some other reason.  By not
-         * returning here until the redraw is complete, you can ensure that
+         * returning from here until the redraw is complete, you can ensure that
          * the user will not see your surface in a bad state (at its new
          * size before it has been correctly drawn that way).  This will
          * typically be preceeded by a call to {@link #surfaceChanged}.
@@ -122,7 +123,7 @@ public interface SurfaceHolder {
 
     /**
      * Add a Callback interface for this holder.  There can several Callback
-     * interfaces associated to a holder.
+     * interfaces associated with a holder.
      * 
      * @param callback The new Callback interface.
      */
@@ -187,7 +188,7 @@ public interface SurfaceHolder {
      * surface is displayed.  The default is false, allowing it to turn off.
      * This is safe to call from any thread.
      * 
-     * @param screenOn Supply to true to force the screen to stay on, false
+     * @param screenOn Set to true to force the screen to stay on, false
      * to allow it to turn off.
      */
     public void setKeepScreenOn(boolean screenOn);
@@ -195,14 +196,14 @@ public interface SurfaceHolder {
     /**
      * Start editing the pixels in the surface.  The returned Canvas can be used
      * to draw into the surface's bitmap.  A null is returned if the surface has
-     * not been created or otherwise can not be edited.  You will usually need
+     * not been created or otherwise cannot be edited.  You will usually need
      * to implement {@link Callback#surfaceCreated Callback.surfaceCreated}
      * to find out when the Surface is available for use.
      * 
      * <p>The content of the Surface is never preserved between unlockCanvas() and
      * lockCanvas(), for this reason, every pixel within the Surface area
      * must be written. The only exception to this rule is when a dirty
-     * rectangle is specified, in which case, non dirty pixels will be
+     * rectangle is specified, in which case, non-dirty pixels will be
      * preserved.
      * 
      * <p>If you call this repeatedly when the Surface is not ready (before
@@ -213,7 +214,7 @@ public interface SurfaceHolder {
      * <p>If null is not returned, this function internally holds a lock until
      * the corresponding {@link #unlockCanvasAndPost} call, preventing
      * {@link SurfaceView} from creating, destroying, or modifying the surface
-     * while it is being drawn.  This can be more convenience than accessing
+     * while it is being drawn.  This can be more convenient than accessing
      * the Surface directly, as you do not need to do special synchronization
      * with a drawing thread in {@link Callback#surfaceDestroyed
      * Callback.surfaceDestroyed}.
@@ -224,7 +225,7 @@ public interface SurfaceHolder {
 
     
     /**
-     * Just like {@link #lockCanvas()} but allows to specify a dirty rectangle.
+     * Just like {@link #lockCanvas()} but allows specification of a dirty rectangle.
      * Every
      * pixel within that rectangle must be written; however pixels outside
      * the dirty rectangle will be preserved by the next call to lockCanvas().

core/java/android/view/SurfaceView.java

@@ -65,7 +65,7 @@ import java.util.concurrent.locks.ReentrantLock;
  * Surface is created and destroyed as the window is shown and hidden.
  * 
  * <p>One of the purposes of this class is to provide a surface in which a
- * secondary thread can render in to the screen.  If you are going to use it
+ * secondary thread can render into the screen.  If you are going to use it
  * this way, you need to be aware of some threading semantics:
  * 
  * <ul>

docs/html/guide/topics/media/index.jd

@@ -115,9 +115,8 @@ Resume playback from where you paused with
 <p>{@link android.media.MediaPlayer#stop() stop()} and 
 {@link android.media.MediaPlayer#pause() pause()} work the same as discussed
 above.</p>
-  <p class="note"><strong>Note:</strong> It is possible that <code>mp</code> could be
-  null, so good code should <code>null</code> check after the <code>new</code>.
-  Also, <code>IllegalArgumentException</code> and <code>IOException</code> either
+  <p class="note"><strong>Note:</strong>
+  <code>IllegalArgumentException</code> and <code>IOException</code> either
   need to be caught or passed on when using <code>setDataSource()</code>, since
   the file you are referencing may not exist.</p>
 <p class="note"><strong>Note:</strong>