Docs: Camera section cleanup (format, links, etc.)

      Adding feedback comments.
      Adding Gina's comments.

Bug: 19234894, 27702676
Change-Id: I40d5e95a310e50aa53d33ae1c84e22f4881a8da3

3 files changed, 269 insertions, 270 deletions

diff --git a/src/devices/camera/camera3.jd b/src/devices/camera/camera3.jd
index 9811a98f..a3fa938c 100644
--- a/src/devices/camera/camera3.jd
+++ b/src/devices/camera/camera3.jd
@@ -1,4 +1,4 @@
-page.title=Camera HAL v3 overview
+page.title=Camera HAL3
 @jd:body
 
 <!--
@@ -25,39 +25,23 @@ page.title=Camera HAL v3 overview
 </div>
 
 <p>
-Android's camera Hardware Abstraction Layer (HAL) connects the higher level 
-camera framework APIs in 
-<a
-href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> 
-to your underlying camera driver and hardware. The latest version of Android 
-introduces a new, underlying implementation of the camera stack. If you have 
-previously developed a camera HAL module and driver for other versions of 
-Android, be aware that there are significant changes in the camera pipeline.</p>
-<p>Version 1 of the camera HAL is still supported for future releases of Android 
-  because many devices still rely on it. Implementing both HALs is also supported 
-  by the Android camera service, which is useful when you want to support a less 
-  capable front-facing camera with version 1 of the HAL and a more advanced 
-  back-facing camera with version 3 of the HAL. Version 2 was a stepping stone to 
-  version 3 and is not supported.</p>
-
-<p>
-There is only one camera HAL module (with its own version number, currently 1, 2,
-or 2.1), which lists multiple independent camera devices that each have
-their own version. Camera module v2 or newer is required to support devices v2 or newer, and such
-camera modules can have a mix of camera device versions. This is what we mean
-when we say Android supports implementing both HALs.
-</p>
+Android's camera Hardware Abstraction Layer (HAL) connects the higher level
+camera framework APIs in
+<a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>
+to your underlying camera driver and hardware. Android 5.0 introduced a new,
+underlying implementation of the camera stack. If you have previously developed
+a camera HAL module and driver for older versions of Android, be aware of
+significant changes in the camera pipeline.</p>
 
 <p class="note"><strong>Note:</strong> The new camera HAL is in active
-development and can change at any time. This document describes at a high level
-the design of the camera subsystem and omits many details. See <a
-href="versioning.html">Camera version support</a> for our plans.</p>
+development and can change at any time. This document describes the high-level
+design of the camera subsystem; for details, see
+<a href="{@docRoot}devices/camera/versioning.html">Camera Version Support</a>.</p>
 
-<h2 id="overview">Overview</h2>
+<h2 id="overview">Camera HAL1 overview</h2>
 
-<p>
-Version 1 of the camera subsystem was designed as a black box with high-level 
-controls. Roughly speaking, the old subsystem has three operating modes:</p>
+<p>Version 1 of the camera subsystem was designed as a black box with high-level
+controls and the following three operating modes:</p>
 
 <ul>
 <li>Preview</li>
@@ -65,46 +49,59 @@ controls. Roughly speaking, the old subsystem has three operating modes:</p>
 <li>Still Capture</li>
 </ul>
 
-<p>Each mode has slightly different and overlapping capabilities. This made it hard 
-to implement new types of features, such as burst mode, since it would fall 
+<p>Each mode has slightly different and overlapping capabilities. This made it
+hard to implement new types of features, such as burst mode, since it would fall
 between two of these modes.</p>
-<img src="images/camera_block.png" alt="Camera block diagram" id="figure1" />
-<p class="img-caption">
-  <strong>Figure 1.</strong> Camera components
-</p>
 
-<h2 id="v3-enhance">Version 3 enhancements</h2>
-
-<p>The aim of the Android Camera API redesign is to substantially increase the 
-ability of applications to control the camera subsystem on Android devices while 
-reorganizing the API to make it more efficient and maintainable.</p>
-
-<p>The additional control makes it easier to build high-quality camera applications 
-on Android devices that can operate reliably across multiple products while 
-still using device-specific algorithms whenever possible to maximize quality and 
+<img src="images/camera_block.png" alt="Camera block diagram" id="figure1" />
+<p class="img-caption"><strong>Figure 1.</strong> Camera components</p>
+
+<p>Android 7.0 continues to support camera HAL1 as many devices still rely on
+it. In addition, the Android camera service supports implementing both HALs (1
+and 3), which is useful when you want to support a less-capable front-facing
+camera with camera HAL1 and a more advanced back-facing camera with camera
+HAL3.</p>
+
+<p class="note"><strong>Note:</strong> Camera HAL2 is not supported as it was a
+temporary step on the way to camera HAL3.</p>
+
+<p>There is a single camera HAL <em>module</em> (with its own
+<a href="{@docRoot}devices/camera/versioning.html#module_version">version
+number</a>), which lists multiple independent camera devices that each have
+their own version number. Camera module 2 or newer is required to support
+devices 2 or newer, and such camera modules can have a mix of camera device
+versions (this is what we mean when we say Android supports implementing both
+HALs).</p>
+
+<h2 id="v3-enhance">Camera HAL3 enhancements</h2>
+
+<p>The aim of the Android Camera API redesign is to substantially increase the
+ability of applications to control the camera subsystem on Android devices while
+reorganizing the API to make it more efficient and maintainable. The additional
+control makes it easier to build high-quality camera applications on Android
+devices that can operate reliably across multiple products while still using
+device-specific algorithms whenever possible to maximize quality and
 performance.</p>
 
-<p>Version 3 of the camera subsystem structures the operation modes into a single 
-unified view, which can be used to implement any of the previous modes and 
-several others, such as burst mode. This results in better user control for 
-focus and exposure and more post-processing, such as noise reduction, contrast 
-and sharpening. Further, this simplified view makes it easier for application 
-developers to use the camera's various functions.<br/>
-The API models the camera subsystem as a pipeline that converts incoming 
-requests for frame captures into frames, on a 1:1 basis. The requests 
-encapsulate all configuration information about the capture and processing of a 
-frame. This includes: resolution and pixel format; manual sensor, lens and flash 
-control; 3A operating modes; RAW->YUV processing control; statistics generation; 
+<p>Version 3 of the camera subsystem structures the operation modes into a
+single unified view, which can be used to implement any of the previous modes
+and several others, such as burst mode. This results in better user control for
+focus and exposure and more post-processing, such as noise reduction, contrast
+and sharpening. Further, this simplified view makes it easier for application
+developers to use the camera's various functions.</p>
+<p>The API models the camera subsystem as a pipeline that converts incoming
+requests for frame captures into frames, on a 1:1 basis. The requests
+encapsulate all configuration information about the capture and processing of a
+frame. This includes resolution and pixel format; manual sensor, lens and flash
+control; 3A operating modes; RAW->YUV processing control; statistics generation;
 and so on.</p>
 
-<p>In simple terms, the application framework requests a frame from the camera 
-subsystem, and the camera subsystem returns results to an output stream. In 
-addition, metadata that contains information such as color spaces and lens 
-shading is generated for each set of results. The following sections and 
-diagrams give you more detail about each component.<br/>
-You can think of camera version 3 as a pipeline to camera version 1's one-way 
-stream. It converts each capture request into one image captured by the sensor, 
-which is processed into: </p>
+<p>In simple terms, the application framework requests a frame from the camera
+subsystem, and the camera subsystem returns results to an output stream. In
+addition, metadata that contains information such as color spaces and lens
+shading is generated for each set of results. You can think of camera version 3
+as a pipeline to camera version 1's one-way stream. It converts each capture
+request into one image captured by the sensor, which is processed into:</p>
 
 <ul>
 <li>A Result object with metadata about the capture.</li>
@@ -114,27 +111,17 @@ which is processed into: </p>
 <p>The set of possible output Surfaces is preconfigured:</p>
 
 <ul>
-<li>Each Surface is a destination for a stream of image buffers of a fixed 
+<li>Each Surface is a destination for a stream of image buffers of a fixed
 resolution.</li>
-<li>Only a small number of Surfaces can be configured as outputs at once (~3).</li>
+<li>Only a small number of Surfaces can be configured as outputs at once (~3).
+</li>
 </ul>
 
-<p>A request contains all desired capture settings and the list of output Surfaces 
-to push image buffers into for this request (out of the total configured set). A 
-request can be one-shot ( with capture() ), or it may be repeated indefinitely 
-(with setRepeatingRequest() ). Captures have priority over repeating
-requests.</p>
+<p>A request contains all desired capture settings and the list of output
+Surfaces to push image buffers into for this request (out of the total
+configured set). A request can be one-shot (with <code>capture()</code>), or it
+may be repeated indefinitely (with <code>setRepeatingRequest()</code>). Captures
+have priority over repeating requests.</p>
+
 <img src="images/camera_simple_model.png" alt="Camera data model" id="figure2" />
-<p class="img-caption">
-  <strong>Figure 2.</strong> Camera core operation model
-</p>
-
-<h2 id="supported-version">Supported version</h2>
-
-<p>Camera devices that support this version of the HAL must return 
-CAMERA_DEVICE_API_VERSION_3_1 in camera_device_t.common.version and in 
-camera_info_t.device_version (from camera_module_t.get_camera_info).<br/>
-Camera modules that may contain version 3.1 devices must implement at least 
-version 2.0 of the camera module interface (as defined by 
-camera_module_t.common.module_api_version).<br/>
-See camera_common.h for more versioning details.</p>
+<p class="img-caption"><strong>Figure 2.</strong> Camera core operation model</p>
diff --git a/src/devices/camera/index.jd b/src/devices/camera/index.jd
index 41f42d56..f56227d1 100644
--- a/src/devices/camera/index.jd
+++ b/src/devices/camera/index.jd
@@ -26,163 +26,166 @@ page.title=Camera
 
 <img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_camera.png" alt="Android Camera HAL icon"/>
 
-<p class="note"><strong>Note:</strong> Please see the following pages for the most up-to-date information:<br>
-<a href="{@docRoot}devices/halref/camera_8h_source.html">camera.h</a> source file<br>
-<a href="{@docRoot}devices/halref/camera3_8h_source.html">camera3.h</a> source file<br>
-<a href="{@docRoot}devices/halref/camera__common_8h_source.html">camera_common.h</a> source file<br>
-<a href="https://developer.android.com/reference/android/hardware/camera2/CameraMetadata.html">CameraMetadata</a> developer reference
-</p>
-
 <p>Android's camera Hardware Abstraction Layer (HAL) connects the higher level
-camera framework APIs in <a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a> to your underlying camera driver and hardware. The camera subsystem includes implementations for camera pipeline components while the camera HAL provides interfaces for use in implementing your version of these components.</p>
+camera framework APIs in
+<a href="http://developer.android.com/reference/android/hardware/package-summary.html">android.hardware</a>
+to your underlying camera driver and hardware. The camera subsystem includes
+implementations for camera pipeline components while the camera HAL provides
+interfaces for use in implementing your version of these components.</p>
+
+<p>For the most up-to-date information, refer to the following resources:</p>
+<ul>
+<li><a href="{@docRoot}devices/halref/camera_8h_source.html">camera.h</a> source
+file</li>
+<li><a href="{@docRoot}devices/halref/camera3_8h_source.html">camera3.h</a>
+source file</li>
+<li><a href="{@docRoot}devices/halref/camera__common_8h_source.html">camera_common.h</a>
+source file</li>
+<li><a href="https://developer.android.com/reference/android/hardware/camera2/CameraMetadata.html">CameraMetadata</a>
+developer reference</li>
+</ul>
+
 
 <h2 id="architecture">Architecture</h2>
-<p>The following figure and list describe the HAL components:
-</p>
+<p>The following figure and list describe the HAL components:</p>
 
 <img src="images/ape_fwk_camera.png" alt="Android camera architecture" id="figure1" />
-<p class="img-caption">
-  <strong>Figure 1.</strong> Camera architecture
-</p>
+<p class="img-caption"><strong>Figure 1.</strong> Camera architecture</p>
 
 <dl>
-  
   <dt>Application framework</dt>
-  <dd>At the application framework level is the app's code, which utilizes the <a 
-  href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>
-  API to interact with the camera hardware. Internally, this code calls a corresponding JNI glue class
-   to access the native code that interacts with the camera.</dd>
-  
+  <dd>At the application framework level is the app's code, which utilizes the
+  <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>
+  API to interact with the camera hardware. Internally, this code calls a
+  corresponding JNI glue class to access the native code that interacts with the
+  camera.</dd>
   <dt>JNI</dt>
-  <dd>The JNI code associated with <a 
-  href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> is located in
-  <code>frameworks/base/core/jni/android_hardware_Camera.cpp</code>. This code calls the lower level
-  native code to obtain access to the physical camera and returns data that is used to create the
- <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> object at the framework level.</dd>
-  
+  <dd>The JNI code associated with <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>
+  is located in
+  <code>frameworks/base/core/jni/android_hardware_Camera.cpp</code>. This code
+  calls the lower level native code to obtain access to the physical camera
+  and returns data that is used to create the
+  <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>
+  object at the framework level.</dd>
   <dt>Native framework<dt>
-  <dd>The native framework defined in <code>frameworks/av/camera/Camera.cpp</code> provides a native equivalent
-  to the <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a> class.
-  This class calls the IPC binder proxies to obtain access to the camera service.</dd>
-  
+  <dd>The native framework defined in <code>frameworks/av/camera/Camera.cpp</code>
+  provides a native equivalent to the
+  <a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>
+  class. This class calls the IPC binder proxies to obtain access to the camera
+  service.</dd>
   <dt>Binder IPC proxies</dt>
-  <dd>The IPC binder proxies facilitate communication over process boundaries. There are three camera binder
-  classes that are located in the <code>frameworks/av/camera</code> directory that calls into
-  camera service.  ICameraService is the interface to the camera service, ICamera is the interface 
-  to a specific opened camera device, and ICameraClient is the device's interface back to the application framework.</dd>
-  
+  <dd>The IPC binder proxies facilitate communication over process boundaries.
+  There are three camera binder classes that are located in
+  <code>frameworks/av/camera</code> directory that calls into camera service.
+  ICameraService is the interface to the camera service, ICamera is the
+  interface to a specific opened camera device, and ICameraClient is the
+  device's interface back to the application framework.</dd>
   <dt>Camera service</dt>
-  <dd>The camera service, located in <code>frameworks/av/services/camera/libcameraservice/CameraService.cpp</code>, is  the actual code that interacts with the HAL.</p>
-
+  <dd>The camera service, located in
+  <code>frameworks/av/services/camera/libcameraservice/CameraService.cpp</code>,
+  is the actual code that interacts with the HAL.</dd>
   <dt>HAL</dt>
-  <dd>The hardware abstraction layer defines the standard interface that the camera service calls into and that
-  you must implement to have your camera hardware function correctly.
-  </dd>
-  
+  <dd>The hardware abstraction layer defines the standard interface that the
+  camera service calls into and that you must implement to have your camera
+  hardware function correctly.</dd>
   <dt>Kernel driver</dt>
-  <dd>The camera's driver interacts with the actual camera hardware and your implementation of the HAL. The
-  camera and driver must support YV12 and NV21 image formats to provide support for
-  previewing the camera image on the display and video recording.</dd>
-  </dl>
-
+  <dd>The camera's driver interacts with the actual camera hardware and your
+  implementation of the HAL. The camera and driver must support YV12 and NV21
+  image formats to provide support for previewing the camera image on the
+  display and video recording.</dd>
+</dl>
 
 <h2 id="implementing">Implementing the HAL</h2>
 <p>The HAL sits between the camera driver and the higher level Android framework
-and defines an interface that you must implement so that apps can
-correctly operate the camera hardware. The HAL interface is defined in the
+and defines an interface you must implement so apps can correctly operate the
+camera hardware. The HAL interface is defined in the
 <code>hardware/libhardware/include/hardware/camera.h</code> and
 <code>hardware/libhardware/include/hardware/camera_common.h</code> header files.
 </p>
 
-<p>
-<code>camera_common.h</code> defines an important struct, <code>camera_module</code>, which defines a standard
-structure to obtain general information about the camera, such as its ID and properties
-that are common to all cameras such as whether or not it is a front or back-facing camera.
-</p>
+<p><code>camera_common.h</code> defines <code>camera_module</code>, a standard
+structure to obtain general information about the camera, such as the camera ID
+and properties common to all cameras (i.e., whether it is a front- or
+back-facing camera).</p>
 
 <p>
-<code>camera.h</code> contains the code that corresponds mainly with
-<a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>. This header file declares a <code>camera_device</code>
-struct that contains a <code>camera_device_ops</code> struct with function pointers
-that point to functions that implement the HAL interface. For documentation on the
-different types of camera parameters that a developer can set, 
-see the <code>frameworks/av/include/camera/CameraParameters.h</code> file.
-These parameters are set with the function pointed to by 
-<code>int (*set_parameters)(struct camera_device *, const char *parms)</code> in the HAL.
+<code>camera.h</code> contains code that corresponds to
+<a href="http://developer.android.com/reference/android/hardware/Camera.html">android.hardware.Camera</a>. This header file declares a
+<code>camera_device</code> struct that in turn contains a
+<code>camera_device_ops</code> struct with pointers to functions that implement
+the HAL interface. For documentation on the camera parameters developers can
+set, refer to <code>frameworks/av/include/camera/CameraParameters.h</code>.
+These parameters are set with the function pointed to by <code>int
+(*set_parameters)(struct camera_device *, const char *parms)</code> in the HAL.
 </p>
 
-<p>For an example of a HAL implementation, see the implementation for the Galaxy Nexus HAL in
-<code>hardware/ti/omap4xxx/camera</code>.</p>
+<p>For an example of a HAL implementation, refer to the implementation for the
+Galaxy Nexus HAL in <code>hardware/ti/omap4xxx/camera</code>.</p>
 
 
-<h2 id="configuring">Configuring the Shared Library</h2>
-<p>You need to set up the Android build system to
-  correctly package the HAL implementation into a shared library and copy it to the
-  appropriate location by creating an <code>Android.mk</code> file:
+<h2 id="configuring">Configuring the shared library</h2>
+<p>Set up the Android build system to correctly package the HAL implementation
+into a shared library and copy it to the appropriate location by creating an
+<code>Android.mk</code> file:</p>
 
 <ol>
-  <li>Create a <code>device/&lt;company_name&gt;/&lt;device_name&gt;/camera</code> directory to contain your 
-  library's source files.</li> 
-  <li>Create an <code>Android.mk</code> file to build the shared library. Ensure that the Makefile contains the following lines:
+<li>Create a <code>device/&lt;company_name&gt;/&lt;device_name&gt;/camera</code>
+directory to contain your library's source files.</li>
+
+<li>Create an <code>Android.mk</code> file to build the shared library. Ensure
+the Makefile contains the following lines:
 <pre>
 LOCAL_MODULE := camera.&lt;device_name&gt;
 LOCAL_MODULE_RELATIVE_PATH := hw
 </pre>
-<p>Notice that your library must be named <code>camera.&lt;device_name&gt;</code> (<code>.so</code> is appended automatically),
-so that Android can correctly load the library. For an example, see the Makefile
-for the Galaxy Nexus camera located in <code>hardware/ti/omap4xxx/Android.mk</code>.</p>
-
-</li>
-<li>Specify that your device has camera features by copying the necessary feature XML files in the
-<code>frameworks/native/data/etc</code> directory with your
-device's Makefile. For example, to specify that your device has a camera flash and can autofocus,
-add the following lines in your device's
-<code>&lt;device&gt;/&lt;company_name&gt;/&lt;device_name&gt;/device.mk</code> Makefile:
-
+<p>Your library must be named <code>camera.&lt;device_name&gt;</code>
+(<code>.so</code> is appended automatically), so Android can correctly load the
+library. For an example, see the Makefile for the Galaxy Nexus camera located in
+<code>hardware/ti/omap4xxx/Android.mk</code>.</p></li>
+
+<li>Specify your device has camera features by copying the necessary feature XML
+files in the <code>frameworks/native/data/etc</code> directory with your
+device's Makefile. For example, to specify your device has a camera flash and
+can autofocus, add the following lines in your device's
+<code>&lt;device&gt;/&lt;company_name&gt;/&lt;device_name&gt;/device.mk</code>
+Makefile:
 <pre class="no-pretty-print">
 PRODUCT_COPY_FILES := \ ...
 
 PRODUCT_COPY_FILES += \
-frameworks/native/data/etc/android.hardware.camera.flash-autofocus.xml:system/etc/permissions/android.hardware.camera.flash-autofocus.xml \    
+frameworks/native/data/etc/android.hardware.camera.flash-autofocus.xml:system/etc/permissions/android.hardware.camera.flash-autofocus.xml \
 </pre>
-
-<p>For an example of a device Makefile, see <code>device/samsung/tuna/device.mk</code>.</p>
-</li>
+<p>For an example of a device Makefile, see
+<code>device/samsung/tuna/device.mk</code>.</p></li>
 
 <li>Declare your camera’s media codec, format, and resolution capabilities in
-<code>device/&lt;company_name&gt;/&lt;device_name&gt;/media_profiles.xml</code> and
-<code>device/&lt;company_name&gt;/&lt;device_name&gt;/media_codecs.xml</code> XML files.
- For more information, see <a href="{@docRoot}devices/media.html#expose"> Exposing
- Codecs and Profiles to the Framework</a> for information on how to do this.
-</p></code>
-
-</li>
+<code>device/&lt;company_name&gt;/&lt;device_name&gt;/media_profiles.xml</code>
+and <code>device/&lt;company_name&gt;/&lt;device_name&gt;/media_codecs.xml</code>
+XML files. For details, see
+<a href="{@docRoot}devices/media/index.html#expose">Exposing codecs to the
+framework</a>.</li>
 
 <li>Add the following lines in your device's
-   <code>device/&lt;company_name&gt;/&lt;device_name&gt;/device.mk</code> 
-  Makefile to copy the <code>media_profiles.xml</code>
-and <code>media_codecs.xml</code> files to the appropriate location:
+<code>device/&lt;company_name&gt;/&lt;device_name&gt;/device.mk</code> Makefile
+to copy the <code>media_profiles.xml</code> and <code>media_codecs.xml</code>
+files to the appropriate location:
 <pre>
 # media config xml file
 PRODUCT_COPY_FILES += \
-    &lt;device&gt;/&lt;company_name&gt;/&lt;device_name&gt;/media_profiles.xml:system/etc/media_profiles.xml
+    &lt;device&gt;/&lt;company&gt;/&lt;device&gt;/media_profiles.xml:system/etc/media_profiles.xml
 
 # media codec config xml file
 PRODUCT_COPY_FILES += \
-    &lt;device&gt;/&lt;company_name&gt;/&lt;device_name&gt;/media_codecs.xml:system/etc/media_codecs.xml
-</pre>
-</li>
+    &lt;device&gt;/&lt;company&gt;/&lt;device&gt;/media_codecs.xml:system/etc/media_codecs.xml
+</pre></li>
 
-<li>
-<p>Declare that you want to include the Camera app in your device's system image by
-specifying it in the <code>PRODUCT_PACKAGES</code> variable in your device's
-   <code>device/&lt;company_name&gt;/&lt;device_name&gt;/device.mk</code> 
-  Makefile:</p>
+<li>To include the Camera app in your device's system image, specify it in the
+<code>PRODUCT_PACKAGES</code> variable in your device's
+<code>device/&lt;company&gt;/&lt;device&gt;/device.mk</code>
+Makefile:
 <pre>
 PRODUCT_PACKAGES := \
 Gallery2 \
 ...
-</pre>
-</li>
-
+</pre></li>
 </ol>
diff --git a/src/devices/camera/versioning.jd b/src/devices/camera/versioning.jd
index 89830991..44d477b6 100644
--- a/src/devices/camera/versioning.jd
+++ b/src/devices/camera/versioning.jd
@@ -1,4 +1,4 @@
-page.title=Camera version support
+page.title=Camera Version Support
 @jd:body
 
 <!--
@@ -65,7 +65,7 @@ API1.</dd>
 
 
 <h2 id=camera_apis>Camera APIs</h2>
-
+<p>Android includes the following camera APIs.</p>
 
 <h3 id=camera_api1>Camera API1</h3>
 
@@ -75,8 +75,9 @@ be lengthy, and Android releases will continue to support Camera API1 apps for
 some time. Specifically, support continues for:</p>
 
 <ul>
-<li><em>Camera API1 interfaces for apps</em>. Camera apps built on top of Camera API1
-should work as they do on devices running earlier Android release versions.</li>
+<li><em>Camera API1 interfaces for apps</em>. Camera apps built on top of Camera
+API1 should work as they do on devices running earlier Android release versions.
+</li>
 <li><em>Camera HAL versions</em>. Includes support for Camera HAL1.0.</li>
 </ul>
 
@@ -249,23 +250,24 @@ Checklist</a>.</p>
 <p>Minor additions to supported metadata and changes to data_space support:</p>
 
 <ul>
-  <li>Add ANDROID_SENSOR_OPAQUE_RAW_SIZE static metadata as mandatory if
-  RAW_OPAQUE format is supported.</li>
-  <li>Add ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE static metadata as
-  mandatory if any RAW format is supported.</li>
-  <li>Switch camera3_stream_t data_space field to a more flexible definition,
-  using the version 0 definition of dataspace encoding.</li>
-  <li>General metadata additions which are available to use for HALv3.2 or
-  newer:
-    <ul>
-      <li><a href="https://developer.android.com/reference/android/hardware/camera2/CameraMetadata.html#INFO_SUPPORTED_HARDWARE_LEVEL_3">ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3</a></li>
-      <li>ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST</li>
-      <li>ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE</li>
-      <li>ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL</li>
-      <li>ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL</li>
-      <li>ANDROID_SENSOR_OPAQUE_RAW_SIZE</li>
-      <li>ANDROID_SENSOR_OPTICAL_BLACK_REGIONS</li>
-    </ul>
+<li>Add <code>ANDROID_SENSOR_OPAQUE_RAW_SIZE</code> static metadata as mandatory
+if <code>RAW_OPAQUE</code> format is supported.</li>
+<li>Add <code>ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE</code> static
+metadata as mandatory if any RAW format is supported.</li>
+<li>Switch <code>camera3_stream_t data_space</code> field to a more flexible
+definition, using the version 0 definition of dataspace encoding.</li>
+<li>General metadata additions which are available to use for HALv3.2 or newer:
+  <ul>
+  <li>
+  <a href="https://developer.android.com/reference/android/hardware/camera2/CameraMetadata.html#INFO_SUPPORTED_HARDWARE_LEVEL_3"><code>ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL_3</code>
+  </a></li>
+  <li><code>ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST</code></li>
+  <li><code>ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST_RANGE</code></li>
+  <li><code>ANDROID_SENSOR_DYNAMIC_BLACK_LEVEL</code></li>
+  <li><code>ANDROID_SENSOR_DYNAMIC_WHITE_LEVEL</code></li>
+  <li><code>ANDROID_SENSOR_OPAQUE_RAW_SIZE</code></li>
+  <li><code>ANDROID_SENSOR_OPTICAL_BLACK_REGIONS</code></li>
+  </ul>
   <li>
 </ul>
 
@@ -276,10 +278,11 @@ Checklist</a>.</p>
 <ul>
   <li>OPAQUE and YUV reprocessing API updates.</li>
   <li>Basic support for depth output buffers.</li>
-  <li>Addition of data_space field to camera3_stream_t.</li>
-  <li>Addition of rotation field to camera3_stream_t.</li>
+  <li>Addition of <code>data_space</code> field to
+  <code>camera3_stream_t</code>.</li>
+  <li>Addition of rotation field to <code>camera3_stream_t</code>.</li>
   <li>Addition of camera3 stream configuration operation mode to
-  camera3_stream_configuration_t.</li>
+  <code>camera3_stream_configuration_t</code>.</li>
 </ul>
 
 <h3 id="32">3.2</h3>
@@ -287,17 +290,20 @@ Checklist</a>.</p>
 <p>Minor revision of expanded-capability HAL:</p>
 
 <ul>
-<li>Deprecates get_metadata_vendor_tag_ops. Use get_vendor_tag_ops in
-camera_common.h instead.</li>
-<li>register_stream_buffers deprecated. All gralloc buffers provided by
-framework to HAL in process_capture_request may be new at any time.</li>
-<li>Add partial result support. process_capture_result may be called multiple
-times with a subset of the available result before the full result is available.</li>
-<li>Add manual template to camera3_request_template. The applications may use
-this template to control the capture settings directly.</li>
+<li>Deprecates <code>get_metadata_vendor_tag_ops</code>. Use
+<code>get_vendor_tag_ops</code> in <code>camera_common.h</code> instead.</li>
+<li>Deprecates <code>register_stream_buffers</code>. All gralloc buffers
+provided by framework to HAL in <code>process_capture_request</code> may be new
+at any time.</li>
+<li>Add partial result support. <code>process_capture_result</code> may be
+called multiple times with a subset of the available results before the full
+result is available.</li>
+<li>Add manual template to <code>camera3_request_template</code>. Applications
+may use this template to control the capture settings directly.</li>
 <li>Rework the bidirectional and input stream specifications.</li>
 <li>Change the input buffer return path. The buffer is returned in
-process_capture_result instead of process_capture_request.</li>
+<code>process_capture_result</code> instead of
+<code>process_capture_request</code>.</li>
 </ul>
 
 <h3 id="31">3.1</h3>
@@ -305,7 +311,7 @@ process_capture_result instead of process_capture_request.</li>
 <p>Minor revision of expanded-capability HAL:</p>
 
 <ul>
-<li>configure_streams passes consumer usage flags to the HAL.</li>
+<li><code>configure_streams</code> passes consumer usage flags to the HAL.</li>
 <li>flush call to drop all in-flight requests/buffers as fast as possible.</li>
 </ul>
 
@@ -321,7 +327,7 @@ with next request and stream buffers already dequeued. Sync framework support
 is included, necessary for efficient implementations.</li>
 <li>Moved triggers into requests, most notifications into results.</li>
 <li>Consolidated all callbacks into framework into one structure, and all setup
-methods into a single initialize() call.</li>
+methods into a single <code>initialize()</code> call.</li>
 <li>Made stream configuration into a single call to simplify stream management.
 Bidirectional streams replace STREAM_FROM_STREAM construct.</li>
 <li>Limited mode semantics for older/limited hardware devices.</li>
@@ -332,10 +338,11 @@ Bidirectional streams replace STREAM_FROM_STREAM construct.</li>
 <p>Initial release of expanded-capability HAL (Android 4.2) [camera2.h]:</p>
 
 <ul>
-<li>Sufficient for implementing existing android.hardware.Camera API.</li>
-<li>Allows for ZSL queue in camera service layer</li>
-<li>Not tested for any new features such manual capture control, Bayer RAW
-capture, reprocessing of RAW data.</li>
+<li>Sufficient for implementing existing <code>android.hardware.Camera</code>
+API.</li>
+<li>Allows for ZSL queue in camera service layer.</li>
+<li>Not tested for any new features such as manual capture control, Bayer RAW
+capture, reprocessing of RAW data, etc.</li>
 </ul>
 
 <h3 id="10">1.0</strong></h3>
@@ -344,63 +351,63 @@ capture, reprocessing of RAW data.</li>
 
 <ul>
 <li>Converted from C++ CameraHardwareInterface abstraction layer.</li>
-<li>Supports android.hardware.Camera API.</li>
+<li>Supports <code>android.hardware.Camera</code> API.</li>
 </ul>
 
-<h2 id="version-history">Camera module version history</h2>
+<h2 id=module_version>Camera module version history</h2>
 
-<p>
-This section contains module versioning information for the Camera hardware module, based on
-camera_module_t.common.module_api_version. The two most significant hex
-digits represent the major version, and the two least significant represent
-the minor version.
-</p>
+<p>This section contains module versioning information for the Camera hardware
+module, based on <code>camera_module_t.common.module_api_version</code>. The two
+most significant hex digits represent the major version, and the two least
+significant represent the minor version.</p>
 
 <h3 id="24">2_4</h3>
 
-<p>This camera module version adds below API changes:</p>
+<p>This camera module version adds the following API changes:</p>
 
 <ol>
-  <li>Torch mode support. The framework can use it to turn on torch mode for
- any camera device that has a flash unit, without opening a camera device. The
+ <li><em>Torch mode support</em>. The framework can turn on torch mode for any
+ camera device that has a flash unit, without opening a camera device. The
  camera device has a higher priority accessing the flash unit than the camera
  module; opening a camera device will turn off the torch if it had been enabled
  through the module interface. When there are any resource conflicts, such as
- open() is called to open a camera device, the camera HAL module must notify the
- framework through the torch mode status callback that the torch mode has been
- turned off.</li>
-
-  <li>External camera (e.g. USB hot-plug camera) support. The API updates specify that
- the camera static info is only available when camera is connected and ready to
- use for external hot-plug cameras. Calls to get static info will be invalid
- calls when camera status is not CAMERA_DEVICE_STATUS_PRESENT. The frameworks
- will only count on device status change callbacks to manage the available external
- camera list.</li>
-
- <li>Camera arbitration hints. This module version adds support for explicitly
- indicating the number of camera devices that can be simultaneously opened and used.
- To specify valid combinations of devices, the resource_cost and conflicting_devices
- fields should always be set in the camera_info structure returned by the
- get_camera_info call.</li>
-
- <li>Module initialization method. This will be called by the camera service
- right after the HAL module is loaded, to allow for one-time initialization
- of the HAL. It is called before any other module methods are invoked.</li>
+ <code>open()</code> is called to open a camera device, the camera HAL module
+ must notify the framework through the torch mode status callback that the torch
+ mode has been turned off.</li>
+
+ <li><em>External camera (e.g. USB hot-plug camera) support</em>. The API
+ updates specify the camera static info is available only when camera is
+ connected and ready to use for external hot-plug cameras. Calls to get static
+ info will be invalid calls when camera status is not
+ <code>CAMERA_DEVICE_STATUS_PRESENT</code>. The framework counts solely on
+ device status change callbacks to manage the available external camera list.
+ </li>
+
+ <li><em>Camera arbitration hints</em>. Adds support for explicitly indicating
+ the number of camera devices that can be simultaneously opened and used. To
+ specify valid combinations of devices, the <code>resource_cost</code> and
+ <code>conflicting_devices</code> fields should always be set in the
+ <code>camera_info</code> structure returned by the <code>get_camera_info</code>
+ call.</li>
+
+ <li><em>Module initialization method</em>. Called by the camera service
+ after the HAL module is loaded to allow for one-time initialization of the HAL.
+ It is called before any other module methods are invoked.</li>
 </ol>
 
 <h3 id="23">2_3</h3>
 
 <p>This camera module version adds open legacy camera HAL device support.
- Framework can use it to open the camera device as lower device HAL version
+ The framework can use it to open the camera device as lower device HAL version
  HAL device if the same device can support multiple device API versions.
  The standard hardware module open call (common.methods->open) continues
  to open the camera device with the latest supported version, which is
- also the version listed in camera_info_t.device_version.</p>
+ also the version listed in <code>camera_info_t.device_version</code>.</p>
 
 <h3 id="22">2_2</h3>
 
 <p>This camera module version adds vendor tag support from the module, and
-deprecates the old vendor_tag_query_ops that were previously only
+deprecates the old <code>vendor_tag_query_ops</code> that were previously only
 accessible with a device open.</p>
 
 <h3 id="21">2_1</h3>
@@ -408,22 +415,24 @@ accessible with a device open.</p>
 <p>This camera module version adds support for asynchronous callbacks to the
 framework from the camera HAL module, which is used to notify the framework
 about changes to the camera module state. Modules that provide a valid
-set_callbacks() method must report at least this version number.</p>
+<code>set_callbacks()</code> method must report at least this version number.</p>
 
 <h3 id="20">2_0</h3>
 
 <p>Camera modules that report this version number implement the second version
 of the camera module HAL interface. Camera devices openable through this
 module may support either version 1.0 or version 2.0 of the camera device
-HAL interface. The device_version field of camera_info is always valid; the
-static_camera_characteristics field of camera_info is valid if the
-device_version field is 2.0 or higher.</p>
+HAL interface. The <code>device_version</code> field of camera_info is always
+valid; the <code>static_camera_characteristics</code> field of
+<code>camera_info</code> is valid if the <code>device_version</code> field is
+2.0 or higher.</p>
 
 <h3 id="10">1_0</h3>
 
 <p>Camera modules that report these version numbers implement the initial
 camera module HAL interface. All camera devices openable through this
-module support only version 1 of the camera device HAL. The device_version
-and static_camera_characteristics fields of camera_info are not valid. Only
-the android.hardware.Camera API can be supported by this module and its
+module support only version 1 of the camera device HAL. The
+<code>device_version</code> and <code>static_camera_characteristics</code>
+fields of <code>camera_info</code> are not valid. Only the
+<code>android.hardware.Camera</code> API can be supported by this module and its
 devices.</p>