Documentation fixes found over vacation hacking.
Change-Id: I28900026465d66d950cf4f05f0c202b46c3c2d43
diff --git a/core/java/android/app/AlertDialog.java b/core/java/android/app/AlertDialog.java
index 2714de5..b459320 100644
--- a/core/java/android/app/AlertDialog.java
+++ b/core/java/android/app/AlertDialog.java
@@ -428,7 +428,7 @@
}
/**
- * 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
*/
diff --git a/core/java/android/database/sqlite/SQLiteDatabase.java b/core/java/android/database/sqlite/SQLiteDatabase.java
index cdc9bbb..a0e9d02 100644
--- a/core/java/android/database/sqlite/SQLiteDatabase.java
+++ b/core/java/android/database/sqlite/SQLiteDatabase.java
@@ -1409,9 +1409,13 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
/**
* 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 @@
/**
* 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();
diff --git a/core/java/android/hardware/Camera.java b/core/java/android/hardware/Camera.java
index f3b2c81..dee1d03 100644
--- a/core/java/android/hardware/Camera.java
+++ b/core/java/android/hardware/Camera.java
@@ -183,10 +183,10 @@
* 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 @@
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 @@
* 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 @@
* 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 @@
* }
* mParameters.setRotation(rotation);
* }
+ * </pre>
*
* @param rotation The rotation angle in degrees relative to the
* orientation of the camera. Rotation can only be 0,
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 6590497..1766345 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -9127,7 +9127,7 @@
*
* @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);
}
diff --git a/docs/html/guide/appendix/faq/commontasks.jd b/docs/html/guide/appendix/faq/commontasks.jd
index 38a89ef..b3dc236 100644
--- a/docs/html/guide/appendix/faq/commontasks.jd
+++ b/docs/html/guide/appendix/faq/commontasks.jd
@@ -655,7 +655,7 @@
and <code>STRIKE</code> (strikethrough).
So, for example, in res/values/strings.xml you could declare this:<br />
<code><resource><br />
- <string>id="@+id/styled_welcome_message">We
+ <string id="@+id/styled_welcome_message">We
are <b><i>so</i></b> glad to see you.</string><br />
</resources></code></li>
<li>To style text on the fly, or to add highlighting or more complex styling,
diff --git a/docs/html/resources/articles/contacts.jd b/docs/html/resources/articles/contacts.jd
index bdf84e6..c837dc3 100644
--- a/docs/html/resources/articles/contacts.jd
+++ b/docs/html/resources/articles/contacts.jd
@@ -107,7 +107,7 @@
<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>
diff --git a/docs/html/resources/faq/commontasks.jd b/docs/html/resources/faq/commontasks.jd
index 9c32e9c..1173725 100644
--- a/docs/html/resources/faq/commontasks.jd
+++ b/docs/html/resources/faq/commontasks.jd
@@ -655,7 +655,7 @@
and <code>STRIKE</code> (strikethrough).
So, for example, in res/values/strings.xml you could declare this:<br />
<code><resource><br />
- <string>id="@+id/styled_welcome_message">We
+ <string id="@+id/styled_welcome_message">We
are <b><i>so</i></b> glad to see you.</string><br />
</resources></code></li>
<li>To style text on the fly, or to add highlighting or more complex styling,
diff --git a/graphics/java/android/graphics/drawable/Drawable.java b/graphics/java/android/graphics/drawable/Drawable.java
index 3125321..9655125 100644
--- a/graphics/java/android/graphics/drawable/Drawable.java
+++ b/graphics/java/android/graphics/drawable/Drawable.java
@@ -202,7 +202,7 @@
/**
* 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