Documentation fixes found over vacation hacking.

Change-Id: I28900026465d66d950cf4f05f0c202b46c3c2d43

Author: bradfitz

core/java/android/app/AlertDialog.java

@@ -428,7 +428,7 @@ public Builder setNeutralButton(CharSequence text, final OnClickListener listene
         }
 
         /**
-         * 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 Cursor rawQuery(String sql, String[] selectionArgs,
      * 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,
-     *            so if initialValues is empty this column will explicitly be
-     *            assigned a NULL value
+     * @param nullColumnHack optional; may be <code>null</code>.
+     *            SQL doesn't allow inserting a completely empty row without
+     *            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 long insert(String table, String nullColumnHack, ContentValues values) {
      * 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,
-     *            so if initialValues is empty this column will explicitly be
-     *            assigned a NULL value
+     * @param nullColumnHack optional; may be <code>null</code>.
+     *            SQL doesn't allow inserting a completely empty row without
+     *            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 long insertOrThrow(String table, String nullColumnHack, ContentValues val
      * 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,
-     *            so if initialValues is empty this row will explicitly be
-     *            assigned a NULL value
+     * @param nullColumnHack optional; may be <code>null</code>.
+     *            SQL doesn't allow inserting a completely empty row without
+     *            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 long replace(String table, String nullColumnHack, ContentValues initialVa
      * 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,
-     *            so if initialValues is empty this row will explicitly be
-     *            assigned a NULL value
+     * @param nullColumnHack optional; may be <code>null</code>.
+     *            SQL doesn't allow inserting a completely empty row without
+     *            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 long replaceOrThrow(String table, String nullColumnHack,
      * 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,
-     *            so if initialValues is empty this column will explicitly be
-     *            assigned a NULL value
+     * @param nullColumnHack optional; may be <code>null</code>.
+     *            SQL doesn't allow inserting a completely empty row without
+     *            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 int updateWithOnConflict(String table, ContentValues values,
 
     /**
      * Execute a single SQL statement that is not a query. For example, CREATE
-     * TABLE, DELETE, INSERT, etc. Multiple statements separated by ;s are not
-     * supported. it takes a write lock
+     * TABLE, DELETE, INSERT, etc. Multiple statements separated by semicolons are not
+     * 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 void execSQL(String sql) throws SQLException {
 
     /**
      * Execute a single SQL statement that is not a query. For example, CREATE
-     * TABLE, DELETE, INSERT, etc. Multiple statements separated by ;s are not
-     * supported. it takes a write lock,
+     * TABLE, DELETE, INSERT, etc. Multiple statements separated by semicolons are not
+     * 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 static class CameraInfo {
          * the right of the screen, the value should be 270.
          *
          * @see #setDisplayOrientation(int)
-         * @see #setRotation(int)
-         * @see #setPreviewSize(int, int)
-         * @see #setPictureSize(int, int)
-         * @see #setJpegThumbnailSize(int, int)
+         * @see Parameters#setRotation(int)
+         * @see Parameters#setPreviewSize(int, int)
+         * @see Parameters#setPictureSize(int, int)
+         * @see Parameters#setJpegThumbnailSize(int, int)
          */
         public int orientation;
     };
@@ -609,9 +609,10 @@ private static void postEventFromNative(Object camera_ref,
     public interface AutoFocusCallback
     {
         /**
-         * Called when the camera auto focus completes.  If the camera does not
-         * support auto-focus and autoFocus is called, onAutoFocus will be
-         * called immediately with success.
+         * Called when the camera auto focus completes.  If the camera
+         * does not support auto-focus and autoFocus is called,
+         * 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 final void takePicture(ShutterCallback shutter, PictureCallback raw,
      * 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
-     * the display, you can use the following code.<p>
+     * <p>If you want to make the camera image show in the same orientation as
+     * 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 @@ private int pixelFormatForCameraFormat(String format) {
          * 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 @@ private int pixelFormatForCameraFormat(String format) {
          *     }
          *     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 interface OnLongClickListener {
          *
          * @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/articles/contacts.jd

@@ -107,7 +107,7 @@ disable aggregation altogether, as described in the sections below.</p>
 <p>When a raw contact is added or modified, the system looks for matching
 (overlapping) raw contacts with which to aggregate it. It may not find any
 matching raw contacts, in which case it will create an aggregate contact that
-contains just the original raw contact. If it finds a single match,it creates a
+contains just the original raw contact. If it finds a single match, it creates a
 new contact that contains the two raw contacts. And it may even find multiple
 similar raw contacts, in which case it chooses the closest match. </p>
 

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 void setChangingConfigurations(int configs) {
 
     /**
      * 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