Improved ChibiOS\EX documentation (almost complete)

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@10285 35acf78f-673a-0410-8e92-d51de3d6d3f4

10 files changed, 71 insertions, 14 deletions

diff --git a/os/ex/ST/hts221.c b/os/ex/ST/hts221.c
index 69ca9da56..23624d888 100644
--- a/os/ex/ST/hts221.c
+++ b/os/ex/ST/hts221.c
@@ -101,7 +101,7 @@ msg_t hts221I2CWriteRegister(I2CDriver *i2cp, uint8_t* txbuf, size_t n) {
  *          calibration registers.

  * @notapi

  *

- * @param[in] dev        pointer to the HTS221 interface

+ * @param[in] devp       pointer to the HTS221 interface

  * @param[in] flag       flag to select parameters

  * @return               the operation status.

  */

diff --git a/os/ex/ST/l3gd20.c b/os/ex/ST/l3gd20.c
index f9c645c4e..066e11962 100644
--- a/os/ex/ST/l3gd20.c
+++ b/os/ex/ST/l3gd20.c
@@ -57,12 +57,12 @@
  * @param[in] b         pointer to an output buffer.
  */
 static void l3gd20SPIReadRegister(SPIDriver *spip, uint8_t reg,  size_t n,
-                                     uint8_t* rxbuf) {
+                                     uint8_t* b) {
   uint8_t cmd;
   (n == 1) ? (cmd = reg | L3GD20_RW) : (cmd = reg | L3GD20_RW | L3GD20_MS);
   spiSelect(spip);
   spiSend(spip, 1, &cmd);
-  spiReceive(spip, n, rxbuf);
+  spiReceive(spip, n, b);
   spiUnselect(spip);
 }
 
@@ -73,7 +73,7 @@ static void l3gd20SPIReadRegister(SPIDriver *spip, uint8_t reg,  size_t n,
  * @param[in] spip      pointer to the SPI interface
  * @param[in] reg       starting register address
  * @param[in] n         number of adjacent registers to write
- * @param[in] value     pointer to a buffer of values.
+ * @param[in] b         pointer to a buffer of values.
  */
 static void l3gd20SPIWriteRegister(SPIDriver *spip, uint8_t reg, size_t n,
                                    uint8_t* b) {
diff --git a/os/ex/ST/l3gd20.h b/os/ex/ST/l3gd20.h
index 968921e73..12770fcdd 100644
--- a/os/ex/ST/l3gd20.h
+++ b/os/ex/ST/l3gd20.h
@@ -379,7 +379,7 @@ typedef enum {
 
 /**
  * @brief   L3GD20 LP2 filter mode.
- * @detail  To activate LP2 HP should be active
+ * @details To activate LP2 HP should be active
  */
 typedef enum {
   L3GD20_LP2M_ON = 0x00,            /**< LP2 filter activated.              */
@@ -467,7 +467,7 @@ typedef struct {
   l3gd20_hpcf_t             hpconfiguration;
   /**
    * @brief   L3GD20 LP2 filter mode.
-   * @detail  To activate LP2 HP should be active
+   * @details To activate LP2 HP should be active
    */
   l3gd20_lp2m_t             lp2mode;
 #endif
diff --git a/os/ex/ST/lis302dl.c b/os/ex/ST/lis302dl.c
index 87b19ee62..cf5e96260 100644
--- a/os/ex/ST/lis302dl.c
+++ b/os/ex/ST/lis302dl.c
@@ -73,7 +73,7 @@ static void lis302dlSPIReadRegister(SPIDriver *spip, uint8_t reg,  size_t n,
  * @param[in] spip      pointer to the SPI interface

  * @param[in] reg       starting register address

  * @param[in] n         number of adjacent registers to write

- * @param[in] value     pointer to a buffer of values.

+ * @param[in] b         pointer to a buffer of values.

  */

 static void lis302dlSPIWriteRegister(SPIDriver *spip, uint8_t reg, size_t n,

                                      uint8_t* b) {

diff --git a/os/ex/ST/lis302dl.h b/os/ex/ST/lis302dl.h
index bad466fd7..b2d3d5cca 100644
--- a/os/ex/ST/lis302dl.h
+++ b/os/ex/ST/lis302dl.h
@@ -161,6 +161,7 @@
 #define LIS302DL_CTRL_REG3_PP_OD    (1 << 6)    /**< Push-pull open-drain     */

 #define LIS302DL_CTRL_REG3_IHL      (1 << 7)    /**< Int active high low      */

 /** @} */

+

 /*===========================================================================*/

 /* Driver pre-compile time settings.                                         */

 /*===========================================================================*/

@@ -335,7 +336,7 @@ typedef struct LIS302DLDriver LIS302DLDriver;
 

 

 /**

- * @extends BaseAccelerometerVMT.

+ * @extends BaseAccelerometerVMT

  *

  * @brief   @p LIS302DL virtual methods table.

  */

@@ -360,7 +361,7 @@ struct LIS302DLVMT {
   float                     fullscale;

 

 /**

- * @extends BaseAccelerometer.

+ * @extends BaseAccelerometer

  *

  * @brief   LIS302DL 3-axis accelerometer class.

  * @details This class extends @p BaseAccelerometer by adding physical

diff --git a/os/ex/ST/lis3dsh.c b/os/ex/ST/lis3dsh.c
index 61039987e..f156ed44b 100644
--- a/os/ex/ST/lis3dsh.c
+++ b/os/ex/ST/lis3dsh.c
@@ -75,7 +75,7 @@ static void lis3dshSPIReadRegister(SPIDriver *spip, uint8_t reg,  size_t n,
  * @param[in] spip      pointer to the SPI interface

  * @param[in] reg       starting register address

  * @param[in] n         number of adjacent registers to write

- * @param[in] value     pointer to a buffer of values.

+ * @param[in] b         pointer to a buffer of values.

  */

 static void lis3dshSPIWriteRegister(SPIDriver *spip, uint8_t reg, size_t n,

                                     uint8_t* b) {

diff --git a/os/ex/dox/flash.dox b/os/ex/dox/flash.dox
new file mode 100644
index 000000000..001d1df9a
--- /dev/null
+++ b/os/ex/dox/flash.dox
@@ -0,0 +1,22 @@
+/*

+    ChibiOS - Copyright (C) 2006..2016 Giovanni Di Sirio

+

+    Licensed under the Apache License, Version 2.0 (the "License");

+    you may not use this file except in compliance with the License.

+    You may obtain a copy of the License at

+

+        http://www.apache.org/licenses/LICENSE-2.0

+

+    Unless required by applicable law or agreed to in writing, software

+    distributed under the License is distributed on an "AS IS" BASIS,

+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

+    See the License for the specific language governing permissions and

+    limitations under the License.

+*/

+

+/**

+ * @defgroup HAL_FLASH Generic Flash Driver Interface

+ * @brief   HAL Generic Flash Driver Interface.

+ *

+ * @ingroup HAL_PERIPHERAL_INTERFACES

+ */

diff --git a/os/ex/dox/jesd216flash.dox b/os/ex/dox/jesd216flash.dox
new file mode 100644
index 000000000..4e4c81a44
--- /dev/null
+++ b/os/ex/dox/jesd216flash.dox
@@ -0,0 +1,22 @@
+/*

+    ChibiOS - Copyright (C) 2006..2016 Giovanni Di Sirio

+

+    Licensed under the Apache License, Version 2.0 (the "License");

+    you may not use this file except in compliance with the License.

+    You may obtain a copy of the License at

+

+        http://www.apache.org/licenses/LICENSE-2.0

+

+    Unless required by applicable law or agreed to in writing, software

+    distributed under the License is distributed on an "AS IS" BASIS,

+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

+    See the License for the specific language governing permissions and

+    limitations under the License.

+*/

+

+/**

+ * @defgroup HAL_JESD216_FLASH JESD216 Compliant Flash Driver Interface

+ * @brief   HAL JESD216 Compliant Flash Driver Interface.

+ *

+ * @ingroup HAL_PERIPHERAL_INTERFACES

+ */

diff --git a/os/hal/lib/peripherals/flash/hal_flash.c b/os/hal/lib/peripherals/flash/hal_flash.c
index ce03624cc..7bc0845bb 100644
--- a/os/hal/lib/peripherals/flash/hal_flash.c
+++ b/os/hal/lib/peripherals/flash/hal_flash.c
@@ -50,7 +50,10 @@
  * @brief   Waits until the current erase operation is finished.

  *

  * @param[in] devp      pointer to a @p BaseFlash object

- * @param[in] cb        polling callback or @p NULL

+ * 

+ * @return              An error code.

+ * @retval FLASH_NO_ERROR if there is no erase operation in progress.

+ * @retval FLASH_ERROR_ERASE if the erase operation failed.

  */

 flash_error_t flashWaitErase(BaseFlash *devp) {

 

@@ -71,6 +74,11 @@ flash_error_t flashWaitErase(BaseFlash *devp) {
 

 /**

  * @brief   Returns the offset of a sector.

+ *

+ * @param[in] devp      pointer to a @p BaseFlash object

+ * @param[in] sector    flash sector number

+ *

+ * @return the offset of the sector

  */

 flash_offset_t flashGetSectorOffset(BaseFlash *devp,

                                     flash_sector_t sector) {

@@ -91,6 +99,11 @@ flash_offset_t flashGetSectorOffset(BaseFlash *devp,
 

 /**

  * @brief   Returns the size of a sector.

+ *

+ * @param[in] devp      pointer to a @p BaseFlash object

+ * @param[in] sector    flash sector number

+ *

+ * @return the size of the sector

  */

 uint32_t flashGetSectorSize(BaseFlash *devp,

                             flash_sector_t sector) {

@@ -108,5 +121,4 @@ uint32_t flashGetSectorSize(BaseFlash *devp,
 

   return size;

 }

-

 /** @} */

diff --git a/os/hal/lib/peripherals/flash/hal_flash.h b/os/hal/lib/peripherals/flash/hal_flash.h
index f7066e2ef..f6e83d580 100644
--- a/os/hal/lib/peripherals/flash/hal_flash.h
+++ b/os/hal/lib/peripherals/flash/hal_flash.h
@@ -200,7 +200,7 @@ typedef struct {
  * @brief   Sensors get axes number.

  *

  * @param[in] ip        pointer to a @p BaseFlash or derived class

- * @return              An error code.

+ * @return              A flash device descriptor.

  *

  * @api

  */

@@ -230,7 +230,7 @@ typedef struct {
  * @param[in] ip        pointer to a @p BaseFlash or derived class

  * @param[in] offset    flash offset

  * @param[in] n         number of bytes to be programmed

- * @param[in] wp        pointer to the data buffer

+ * @param[in] pp        pointer to the data buffer

  * @return              An error code.

  * @retval FLASH_NO_ERROR if there is no erase operation in progress.

  * @retval FLASH_BUSY_ERASING if there is an erase operation in progress.