Documentation fixes found over vacation hacking.

Change-Id: I28900026465d66d950cf4f05f0c202b46c3c2d43

core/java/android/app/AlertDialog.java

@@ -428,7 +428,7 @@ public class AlertDialog extends Dialog implements DialogInterface {
         }
         
         /**
-         * Sets whether the dialog is cancelable or not default is true.
+         * Sets whether the dialog is cancelable or not.  Default is true.
          *
          * @return This Builder object to allow for chaining of calls to set methods
          */

core/java/android/database/sqlite/SQLiteDatabase.java

@@ -1409,9 +1409,13 @@ public class SQLiteDatabase extends SQLiteClosable {
      * Convenience method for inserting a row into the database.
      *
      * @param table the table to insert the row into
-     * @param nullColumnHack SQL doesn't allow inserting a completely empty row,
+     * @param nullColumnHack optional; may be <code>null</code>.
-     *            so if initialValues is empty this column will explicitly be
+     *            SQL doesn't allow inserting a completely empty row without
-     *            assigned a NULL value
+     *            naming at least one column name.  If your provided <code>values</code> is
+     *            empty, no column names are known and an empty row can't be inserted.
+     *            If not set to null, the <code>nullColumnHack</code> parameter
+     *            provides the name of nullable column name to explicitly insert a NULL into
+     *            in the case where your <code>values</code> is empty.
      * @param values this map contains the initial column values for the
      *            row. The keys should be the column names and the values the
      *            column values
@@ -1430,9 +1434,13 @@ public class SQLiteDatabase extends SQLiteClosable {
      * Convenience method for inserting a row into the database.
      *
      * @param table the table to insert the row into
-     * @param nullColumnHack SQL doesn't allow inserting a completely empty row,
+     * @param nullColumnHack optional; may be <code>null</code>.
-     *            so if initialValues is empty this column will explicitly be
+     *            SQL doesn't allow inserting a completely empty row without
-     *            assigned a NULL value
+     *            naming at least one column name.  If your provided <code>values</code> is
+     *            empty, no column names are known and an empty row can't be inserted.
+     *            If not set to null, the <code>nullColumnHack</code> parameter
+     *            provides the name of nullable column name to explicitly insert a NULL into
+     *            in the case where your <code>values</code> is empty.
      * @param values this map contains the initial column values for the
      *            row. The keys should be the column names and the values the
      *            column values
@@ -1448,11 +1456,15 @@ public class SQLiteDatabase extends SQLiteClosable {
      * Convenience method for replacing a row in the database.
      *
      * @param table the table in which to replace the row
-     * @param nullColumnHack SQL doesn't allow inserting a completely empty row,
+     * @param nullColumnHack optional; may be <code>null</code>.
-     *            so if initialValues is empty this row will explicitly be
+     *            SQL doesn't allow inserting a completely empty row without
-     *            assigned a NULL value
+     *            naming at least one column name.  If your provided <code>initialValues</code> is
+     *            empty, no column names are known and an empty row can't be inserted.
+     *            If not set to null, the <code>nullColumnHack</code> parameter
+     *            provides the name of nullable column name to explicitly insert a NULL into
+     *            in the case where your <code>initialValues</code> is empty.
      * @param initialValues this map contains the initial column values for
-     *   the row. The key
+     *   the row.
      * @return the row ID of the newly inserted row, or -1 if an error occurred
      */
     public long replace(String table, String nullColumnHack, ContentValues initialValues) {
@@ -1469,9 +1481,13 @@ public class SQLiteDatabase extends SQLiteClosable {
      * Convenience method for replacing a row in the database.
      *
      * @param table the table in which to replace the row
-     * @param nullColumnHack SQL doesn't allow inserting a completely empty row,
+     * @param nullColumnHack optional; may be <code>null</code>.
-     *            so if initialValues is empty this row will explicitly be
+     *            SQL doesn't allow inserting a completely empty row without
-     *            assigned a NULL value
+     *            naming at least one column name.  If your provided <code>initialValues</code> is
+     *            empty, no column names are known and an empty row can't be inserted.
+     *            If not set to null, the <code>nullColumnHack</code> parameter
+     *            provides the name of nullable column name to explicitly insert a NULL into
+     *            in the case where your <code>initialValues</code> is empty.
      * @param initialValues this map contains the initial column values for
      *   the row. The key
      * @throws SQLException
@@ -1487,9 +1503,13 @@ public class SQLiteDatabase extends SQLiteClosable {
      * General method for inserting a row into the database.
      *
      * @param table the table to insert the row into
-     * @param nullColumnHack SQL doesn't allow inserting a completely empty row,
+     * @param nullColumnHack optional; may be <code>null</code>.
-     *            so if initialValues is empty this column will explicitly be
+     *            SQL doesn't allow inserting a completely empty row without
-     *            assigned a NULL value
+     *            naming at least one column name.  If your provided <code>initialValues</code> is
+     *            empty, no column names are known and an empty row can't be inserted.
+     *            If not set to null, the <code>nullColumnHack</code> parameter
+     *            provides the name of nullable column name to explicitly insert a NULL into
+     *            in the case where your <code>initialValues</code> is empty.
      * @param initialValues this map contains the initial column values for the
      *            row. The keys should be the column names and the values the
      *            column values
@@ -1726,10 +1746,10 @@ public class SQLiteDatabase extends SQLiteClosable {
 
     /**
      * Execute a single SQL statement that is not a query. For example, CREATE
-     * TABLE, DELETE, INSERT, etc. Multiple statements separated by ;s are not
+     * TABLE, DELETE, INSERT, etc. Multiple statements separated by semicolons are not
-     * supported. it takes a write lock
+     * supported.  Takes a write lock.
      *
-     * @throws SQLException If the SQL string is invalid for some reason
+     * @throws SQLException if the SQL string is invalid
      */
     public void execSQL(String sql) throws SQLException {
         BlockGuard.getThreadPolicy().onWriteToDisk();
@@ -1760,12 +1780,12 @@ public class SQLiteDatabase extends SQLiteClosable {
 
     /**
      * Execute a single SQL statement that is not a query. For example, CREATE
-     * TABLE, DELETE, INSERT, etc. Multiple statements separated by ;s are not
+     * TABLE, DELETE, INSERT, etc. Multiple statements separated by semicolons are not
-     * supported. it takes a write lock,
+     * supported.  Takes a write lock.
      *
      * @param sql
      * @param bindArgs only byte[], String, Long and Double are supported in bindArgs.
-     * @throws SQLException If the SQL string is invalid for some reason
+     * @throws SQLException if the SQL string is invalid
      */
     public void execSQL(String sql, Object[] bindArgs) throws SQLException {
         BlockGuard.getThreadPolicy().onWriteToDisk();

core/java/android/hardware/Camera.java

@@ -183,10 +183,10 @@ public class Camera {
          * the right of the screen, the value should be 270.
          *
          * @see #setDisplayOrientation(int)
-         * @see #setRotation(int)
+         * @see Parameters#setRotation(int)
-         * @see #setPreviewSize(int, int)
+         * @see Parameters#setPreviewSize(int, int)
-         * @see #setPictureSize(int, int)
+         * @see Parameters#setPictureSize(int, int)
-         * @see #setJpegThumbnailSize(int, int)
+         * @see Parameters#setJpegThumbnailSize(int, int)
          */
         public int orientation;
     };
@@ -609,9 +609,10 @@ public class Camera {
     public interface AutoFocusCallback
     {
         /**
-         * Called when the camera auto focus completes.  If the camera does not
+         * Called when the camera auto focus completes.  If the camera
-         * support auto-focus and autoFocus is called, onAutoFocus will be
+         * does not support auto-focus and autoFocus is called,
-         * called immediately with success.
+         * onAutoFocus will be called immediately with a fake value of
+         * <code>success</code> set to <code>true</code>.
          *
          * @param success true if focus was successful, false if otherwise
          * @param camera  the Camera service object
@@ -785,12 +786,12 @@ public class Camera {
      * is, the image is reflected along the central vertical axis of the camera
      * sensor. So the users can see themselves as looking into a mirror.
      *
-     * This does not affect the order of byte array passed in {@link
+     * <p>This does not affect the order of byte array passed in {@link
      * PreviewCallback#onPreviewFrame}, JPEG pictures, or recorded videos. This
      * method is not allowed to be called during preview.
      *
-     * If you want to make the camera image show in the same orientation as
+     * <p>If you want to make the camera image show in the same orientation as
-     * the display, you can use the following code.<p>
+     * the display, you can use the following code.
      * <pre>
      * public static void setCameraDisplayOrientation(Activity activity,
      *         int cameraId, android.hardware.Camera camera) {
@@ -1767,26 +1768,27 @@ public class Camera {
          * the orientation in the EXIF header will be missing or 1 (row #0 is
          * top and column #0 is left side).
          *
-         * If applications want to rotate the picture to match the orientation
+         * <p>If applications want to rotate the picture to match the orientation
          * of what users see, apps should use {@link
          * android.view.OrientationEventListener} and {@link CameraInfo}.
          * The value from OrientationEventListener is relative to the natural
          * orientation of the device. CameraInfo.orientation is the angle
-         * between camera orientation and natural device orientation. The sum or
+         * between camera orientation and natural device orientation. The sum
          * of the two is the rotation angle for back-facing camera. The
          * difference of the two is the rotation angle for front-facing camera.
          * Note that the JPEG pictures of front-facing cameras are not mirrored
          * as in preview display.
          *
-         * For example, suppose the natural orientation of the device is
+         * <p>For example, suppose the natural orientation of the device is
          * portrait. The device is rotated 270 degrees clockwise, so the device
          * orientation is 270. Suppose a back-facing camera sensor is mounted in
          * landscape and the top side of the camera sensor is aligned with the
          * right edge of the display in natural orientation. So the camera
          * orientation is 90. The rotation should be set to 0 (270 + 90).
          *
-         * The reference code is as follows.
+         * <p>The reference code is as follows.
          *
+	 * <pre>
          * public void public void onOrientationChanged(int orientation) {
          *     if (orientation == ORIENTATION_UNKNOWN) return;
          *     android.hardware.Camera.CameraInfo info =
@@ -1801,6 +1803,7 @@ public class Camera {
          *     }
          *     mParameters.setRotation(rotation);
          * }
+	 * </pre>
          *
          * @param rotation The rotation angle in degrees relative to the
          *                 orientation of the camera. Rotation can only be 0,

core/java/android/view/View.java

@@ -9127,7 +9127,7 @@ public class View implements Drawable.Callback, KeyEvent.Callback, Accessibility
          *
          * @param v The view that was clicked and held.
          *
-         * return True if the callback consumed the long click, false otherwise
+         * @return true if the callback consumed the long click, false otherwise.
          */
         boolean onLongClick(View v);
     }

docs/html/guide/appendix/faq/commontasks.jd

@@ -655,7 +655,7 @@ and the {@link android.os.Handler} documentation.</p>
         and <code>STRIKE</code> (strikethrough).
         So, for example, in res/values/strings.xml you could declare this:<br />
         <code>&lt;resource&gt;<br />
-        &nbsp;&nbsp;&nbsp;&nbsp;&lt;string&gt;id=&quot;@+id/styled_welcome_message&quot;&gt;We
+        &nbsp;&nbsp;&nbsp;&nbsp;&lt;string&nbsp;id=&quot;@+id/styled_welcome_message&quot;&gt;We
         are &lt;b&gt;&lt;i&gt;so&lt;/i&gt;&lt;/b&gt; glad to see you.&lt;/string&gt;<br />
         &lt;/resources&gt;</code></li>
     <li>To style text on the fly, or to add highlighting or more complex styling,

docs/html/resources/faq/commontasks.jd

@@ -655,7 +655,7 @@ and the {@link android.os.Handler} documentation.</p>
         and <code>STRIKE</code> (strikethrough).
         So, for example, in res/values/strings.xml you could declare this:<br />
         <code>&lt;resource&gt;<br />
-        &nbsp;&nbsp;&nbsp;&nbsp;&lt;string&gt;id=&quot;@+id/styled_welcome_message&quot;&gt;We
+        &nbsp;&nbsp;&nbsp;&nbsp;&lt;string&nbsp;id=&quot;@+id/styled_welcome_message&quot;&gt;We
         are &lt;b&gt;&lt;i&gt;so&lt;/i&gt;&lt;/b&gt; glad to see you.&lt;/string&gt;<br />
         &lt;/resources&gt;</code></li>
     <li>To style text on the fly, or to add highlighting or more complex styling,

graphics/java/android/graphics/drawable/Drawable.java

@@ -202,7 +202,7 @@ public abstract class Drawable {
 
     /**
      * Return a mask of the configuration parameters for which this drawable
-     * mau change, requiring that it be re-created.  The default implementation
+     * may change, requiring that it be re-created.  The default implementation
      * returns whatever was provided through
      * {@link #setChangingConfigurations(int)} or 0 by default.  Subclasses
      * may extend this to or in the changing configurations of any other