Doc: Edit to the Doxygen guidelines based on feedback.

Added a asterisk in front of every line of the comments to fully comply
with the Javadoc style. Updated all cross-references to comply with the
new style. Added a note indicating explicitly that enums are to be
documented just as structs. 

Change-Id: If017e14e3e478ec28befb5c1fcae92090f91c32e
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>

doc/documentation/rest_cross.rst

@@ -110,8 +110,7 @@ reference to a documented code element.
 
 .. caution::
    References to in-code documentation only work if the element has been
-   documented in the code following the :ref:`In-Code Documentation
-   Guidelines`.
+   documented in the code following the :ref:`code_documentation_guidelines`.
 
 External References
 ===================

doc/doxygen/doxygen_guidelines.rst

@@ -1,23 +1,24 @@
-.. _In-Code Documentation Guidelines:
+.. _code_documentation_guidelines:
 
 In-Code Documentation Guidelines
 ################################
 
-Follow these guidelines to document your code using comments. We
-provide examples on how to comment different parts of the code. Files,
-functions, defines, structures, variables and type definitions must be
-documented.
+Follow these guidelines to document your code using comments. The |project|
+follows the Javadoc Doxygen comments style. We provide examples on how to
+comment different parts of the code. Files, functions, defines, structures,
+variables and type definitions must be documented.
 
 We have grouped the guidelines according to the object that is being
-documented. Read the information regarding all elements carefully since
-each type of object provides further details as to how to document the
-code as a whole.
+documented. Read sections carefully since each object provides further
+details as to how to document the code as a whole.
 
 These simple rules apply to all the code that you wish to include in
 the documentation:
 
 #. Start and end a comment block with :literal:`/**` and :literal:`*/`
 
+#. Start each line of the comment with :literal:` * `
+
 #. Use \@ for all Doxygen special commands.
 
 #. Files, functions, defines, structures, variables and type
@@ -26,7 +27,7 @@ the documentation:
 #. All comments must start with a capital letter and end in a period.
    Even if the comment is a sentence fragment.
 
-.. important::
+.. note::
 
    Always use :literal:`/**` This is a comment. :literal:`*/` if that
    comment should become part of the documentation.

doc/doxygen/doxygen_guidelines_defines.rst

@@ -1,4 +1,4 @@
-.. _Define Documentation:
+.. _define_documentation:
 
 Define Documentation
 ####################
@@ -23,11 +23,11 @@ Full template:
 .. code-block:: c
 
    /** @def name_of_define
-
-       @brief Brief description of the define.
-
-       @details Multiple lines describing in detail what is the
-       purpose of the define and what it does.
+     *
+     * @brief Brief description of the define.
+     *
+     * @details Multiple lines describing in detail what is the
+     * purpose of the define and what it does.
    */
 
    #define name_of_define
@@ -37,10 +37,10 @@ Simplified template:
 .. code-block:: c
 
    /**
-       Brief description of the define.
-
-       Multiple lines describing in detail what is the
-       purpose of the define and what it does.
+     * Brief description of the define.
+     *
+     * Multiple lines describing in detail what is the
+     * purpose of the define and what it does.
    */
    #define name_of_define
 

doc/doxygen/doxygen_guidelines_files.rst

@@ -1,4 +1,4 @@
-.. _File Header Documentation:
+.. _file_header_documentation:
 
 File Header Documentation
 #########################
@@ -22,7 +22,8 @@ beginning of the file. The file header must contain:
    (@author), and other important information. Please refer to the
    `Doxygen documentation`_ for further details.
 
-.. _Doxygen documentation: http://www.stack.nl/~dimitri/doxygen/manual/index.html
+.. _Doxygen documentation:
+   http://www.stack.nl/~dimitri/doxygen/manual/index.html
 
 Examples
 ********
@@ -31,8 +32,6 @@ Correct:
 
 * A file header with a single line description.
 
-
-
 .. literalinclude:: hello_commented.c
    :language: c
    :lines: 1-5

doc/doxygen/doxygen_guidelines_functions.rst

@@ -1,4 +1,4 @@
-.. _Function Documentation:
+.. _function_documentation:
 
 Function Documentation
 ######################

doc/doxygen/doxygen_guidelines_structs.rst

@@ -1,4 +1,4 @@
-.. _Structure Documentation:
+.. _structure_documentation:
 
 Structure Documentation
 #######################
@@ -9,6 +9,11 @@ structs only require a brief description detailing why they are needed.
 Each variable that composes a struct must be commented. A fully
 simplified syntax is therefore appropriate.
 
+.. note::
+
+   Follow the same rules as struct when documenting an enum. Use the
+   simplified syntax to add the brief description.
+
 Structure Comments Template
 ***************************
 Structs only have a simplified template:

doc/doxygen/doxygen_guidelines_typedefs.rst

@@ -1,4 +1,4 @@
-.. _Type Definition Documentation:
+.. _type_definition_documentation:
 
 Type Definition Documentation
 #############################

doc/doxygen/doxygen_guidelines_variables.rst

@@ -1,4 +1,4 @@
-.. _Variable Documentation:
+.. _variable_documentation:
 
 Variable Documentation
 ######################

doc/doxygen/hello_commented.c

@@ -46,12 +46,12 @@
  */
 
 /**
- @def SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
- @brief Compute equivalence in ticks.
+ * @def SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
+ * @brief Compute equivalence in ticks.
  */
 /**
- @def SLEEPTIME
- @brief Specify delay between greetings (in ms).
+ * @def SLEEPTIME
+ * @brief Specify delay between greetings (in ms).
  */
 
 #if defined(CONFIG_STDOUT_CONSOLE)
@@ -70,12 +70,12 @@
 #define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
 
 /**
- @brief A loop saying hello.
-
- @details
- Actions:
- 	 -# Ouputs "Hello World!".
- 	 -# Waits, then lets another task run.
+ * @brief A loop saying hello.
+ *
+ * @details
+ * Actions:
+ * 	 -# Ouputs "Hello World!".
+ * 	 -# Waits, then lets another task run.
 
  @param taskname The task's identification string.
  @param mySem    The task's semaphore.
@@ -95,12 +95,12 @@ void helloLoop(const char *taskname, ksem_t mySem, ksem_t otherSem)
 }
 
 /**
- @brief Exchanges Hello messages with taskB.
-
- @details
- Actions:
- 	 -# taskA gives its own semaphore, thus it says hello right away.
- 	 -# Calls function helloLoop, thus taskA exchanges hello messages with taskB.
+ * @brief Exchanges Hello messages with taskB.
+ *
+ * @details
+ * Actions:
+ *  -# taskA gives its own semaphore, thus it says hello right away.
+ *  -# Calls function helloLoop, thus taskA exchanges hello messages with taskB.
  */
 void taskA(void)
 {
@@ -110,10 +110,10 @@ void taskA(void)
 }
 
 /**
- @brief Exchanges Hello messages with taskA.
-
- Actions:
- 	 -# Calls function helloLoop, thus taskB exchanges hello messages with taskA.
+ * @brief Exchanges Hello messages with taskA.
+ *
+ * Actions:
+ *  -# Calls function helloLoop, thus taskB exchanges hello messages with taskA.
  */
 void taskB(void)
 {
@@ -140,14 +140,14 @@ struct nano_sem nanoSemTask;
 struct nano_sem nanoSemFiber;
 
 /**
- @brief Defines the turns taken by the tasks in the fiber.
-
- Actions:
- -# Initializes semaphore.
- -# Initializes timer.
- -# Waits for task, then runs.
- -# Outputs "Hello World!".
- -# Waits, then yields to another task.
+ * @brief Defines the turns taken by the tasks in the fiber.
+ *
+ * Actions:
+ * -# Initializes semaphore.
+ * -# Initializes timer.
+ * -# Waits for task, then runs.
+ * -# Outputs "Hello World!".
+ * -# Waits, then yields to another task.
  */
 void fiberEntry(void) {
 	struct nano_timer timer;
@@ -170,12 +170,12 @@ void fiberEntry(void) {
 }
 
 /**
- @brief Implements the Hello demo.
-
- Actions:
- -# Outputs "hello".
- -# Waits, then signals fiber's semaphore.
- -# Waits on fiber to yield.
+ * @brief Implements the Hello demo.
+ *
+ * Actions:
+ * -# Outputs "hello".
+ * -# Waits, then signals fiber's semaphore.
+ * -# Waits on fiber to yield.
  */
 void main(void) {
 	struct nano_timer timer;

doc/doxygen/phil_commented.h

@@ -44,11 +44,11 @@
 #endif
 
 /**
- @def N_PHILOSOPHERS
- @brief Defines the number of philosophers.
-
-@details Multiple tasks do printfs and they may conflict.
-Uses puts() instead of printf() to avoid conflicts.
+ * @def N_PHILOSOPHERS
+ * @brief Defines the number of philosophers.
+ *
+ * @details Multiple tasks do printfs and they may conflict.
+ * Uses puts() instead of printf() to avoid conflicts.
  */
 
 #define N_PHILOSOPHERS	6