lsm303dlh: add DocBook documentation

Adding DocBook documentation for lsm303dlh accelerometer
and magnetometer drivers.

ST-Ericsson ID: 277198
Change-Id: Idfca43aa6ffaa39b7f73d0135dc6d2b01a0a44c6
Signed-off-by: Chethan Krishna N <chethan.krishna@stericsson.com>
Reviewed-on: http://gerrit.lud.stericsson.com/gerrit/23784
Reviewed-by: Srinidhi KASAGAR <srinidhi.kasagar@stericsson.com>

Conflicts:

	Documentation/DocBook/Makefile

4 files changed, 150 insertions, 24 deletions

diff --git a/Documentation/DocBook/lsm303dlh.tmpl b/Documentation/DocBook/lsm303dlh.tmpl
new file mode 100644
index 00000000000..3b1c6afa65f
--- /dev/null
+++ b/Documentation/DocBook/lsm303dlh.tmpl
@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
+
+<book id="LSM303DLH-API-Guide">
+ <bookinfo>
+  <title>LSM303DLH Accelerometer and Magnetometer</title>
+
+  <authorgroup>
+   <author>
+    <firstname>Chethan Krishna</firstname>
+    <surname>N</surname>
+    <affiliation>
+     <address>
+      <email>chethan.krishna@stericsson.com</email>
+     </address>
+    </affiliation>
+   </author>
+   </authorgroup>
+
+  <copyright>
+   <year>2010</year>
+   <holder>ST-Ericsson</holder>
+  </copyright>
+
+  <subjectset>
+    <subject>
+      <subjectterm>Linux standard functions</subjectterm>
+    </subject>
+  </subjectset>
+
+  <legalnotice>
+   <para>
+     License terms: GNU General Public License (GPL) version 2.
+   </para>
+
+   </legalnotice>
+ </bookinfo>
+
+<toc></toc>
+
+  <chapter id="intro">
+    <title>Introduction</title>
+    <para>
+	This documentation describes the accelerometer and magnetometer drivers for lsm303dlh sensor chip.
+    </para>
+    </chapter>
+
+  <chapter id="bugs">
+     <title>Known Bugs And Assumptions</title>
+  <para>
+     <variablelist>
+     <varlistentry>
+       <term>None</term>
+       <listitem>
+         <para>
+		None.
+           </para>
+       </listitem>
+     </varlistentry>
+     </variablelist>
+  </para>
+  </chapter>
+
+  <chapter id="pubfunctions">
+     <title>Public Functions Provided</title>
+     <para>
+	This accelerometer/magnetometer drivers don't export any functions.
+     </para>
+  </chapter>
+
+  <chapter id="structs">
+     <title>Structures</title>
+     <para>
+     This chapter contains the autogenerated documentation of the structures which are
+     used in the accelerometer/magnetometer drivers.
+     </para>
+!Iinclude/linux/lsm303dlh.h
+  </chapter>
+
+  <chapter id="intfunctions">
+     <title>Internal Functions Provided</title>
+     <para>
+     This chapter contains the autogenerated documentation of the internal functions.
+     </para>
+!Idrivers/hwmon/lsm303dlh_a.c
+!Idrivers/hwmon/lsm303dlh_m.c
+  </chapter>
+
+  </book>
diff --git a/drivers/hwmon/lsm303dlh_a.c b/drivers/hwmon/lsm303dlh_a.c
index 7721310be06..1436e77a0d6 100644
--- a/drivers/hwmon/lsm303dlh_a.c
+++ b/drivers/hwmon/lsm303dlh_a.c
@@ -149,8 +149,27 @@ struct lsm303dlh_a_t {
 	short	z;
 };
 
-/*
- * accelerometer local data
+/**
+ * struct lsm303dlh_a_data - data structure used by lsm303dlh_a driver
+ * @client: i2c client
+ * @lock: mutex lock for sysfs operations
+ * @data: lsm303dlh_a_t struct containing x, y and z values
+ * @input_dev: input device
+ * @input_dev2: input device
+ * @pdata: lsm303dlh platform data
+ * @regulator: regulator
+ * @range: current range value of accelerometer
+ * @mode: current mode of operation
+ * @rate: current sampling rate
+ * @sleep_wake: sleep wake setting
+ * @shift_adjust: current shift adjust value set according to range
+ * @interrupt_control: interrupt control settings
+ * @interrupt_channel: interrupt channel 0 or 1
+ * @interrupt_configure: interrupt configurations for two channels
+ * @interrupt_duration: interrupt duration for two channels
+ * @interrupt_threshold: interrupt threshold for two channels
+ * @early_suspend: early suspend structure
+ * @device_status: device is ON, OFF or SUSPENDED
  */
 struct lsm303dlh_a_data {
 	struct i2c_client *client;
diff --git a/drivers/hwmon/lsm303dlh_m.c b/drivers/hwmon/lsm303dlh_m.c
index 8352b3d0281..42ef63157ae 100644
--- a/drivers/hwmon/lsm303dlh_m.c
+++ b/drivers/hwmon/lsm303dlh_m.c
@@ -125,8 +125,20 @@
 #define DEVICE_ON 1
 #define DEVICE_SUSPENDED 2
 
-/*
- * magnetometer local data
+/**
+ * struct lsm303dlh_m_data - data structure used by lsm303dlh_m driver
+ * @client: i2c client
+ * @lock: mutex lock for sysfs operations
+ * @input_dev: input device
+ * @regulator: regulator
+ * @pdata: lsm303dlh platform data
+ * @gain: x, y and z axes gain
+ * @data: Magnetic field values of x, y and z axes
+ * @mode: current mode of operation
+ * @rate: current sampling rate
+ * @range: current range value of magnetometer
+ * @early_suspend: early suspend structure
+ * @device_status: device is ON, OFF or SUSPENDED
  */
 struct lsm303dlh_m_data {
 	struct i2c_client *client;
diff --git a/include/linux/lsm303dlh.h b/include/linux/lsm303dlh.h
index d9fd6148198..ad369b1fbd5 100644
--- a/include/linux/lsm303dlh.h
+++ b/include/linux/lsm303dlh.h
@@ -29,27 +29,32 @@
 #include <linux/ioctl.h>
 
 #ifdef __KERNEL__
+/**
+ * struct lsm303dlh_platform_data - platform datastructure for lsm303dlh
+ * @name_a: accelerometer name
+ * @name_m: magnetometer name
+ * @irq_a1: interrupt line 1 of accelerometer
+ * @irq_a2: interrupt line 2 of accelerometer
+ * @irq_m: interrupt line of magnetometer
+ * @axis_map_x: x axis position on the hardware, 0 1 or 2
+ * @axis_map_y: y axis position on the hardware, 0 1 or 2
+ * @axis_map_z: z axis position on the hardware, 0 1 or 2
+ * @negative_x: x axis is orientation, 0 or 1
+ * @negative_y: y axis is orientation, 0 or 1
+ * @negative_z: z axis is orientation, 0 or 1
+ */
 struct lsm303dlh_platform_data {
-
-	/* name of device for regulator */
-
-	const char *name_a; /* acelerometer name */
-	const char *name_m; /* magnetometer name */
-
-	/*  interrupt data */
-	u32  irq_a1;      /* interrupt line 1 of accelrometer*/
-	u32  irq_a2;      /* interrupt line 2 of accelrometer*/
-	u32  irq_m;       /* interrupt line of magnetometer*/
-
-	/* position of x,y and z axis */
-	u8  axis_map_x; /* [0-2] */
-	u8  axis_map_y; /* [0-2] */
-	u8  axis_map_z; /* [0-2] */
-
-	/* orientation of x,y and z axis */
-	u8  negative_x; /* [0-1] */
-	u8  negative_y; /* [0-1] */
-	u8  negative_z; /* [0-1] */
+	const char *name_a;
+	const char *name_m;
+	u32  irq_a1;
+	u32  irq_a2;
+	u32  irq_m;
+	u8  axis_map_x;
+	u8  axis_map_y;
+	u8  axis_map_z;
+	u8  negative_x;
+	u8  negative_y;
+	u8  negative_z;
 };
 #endif /* __KERNEL__ */