bartoszek/zephyr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: Change Doxygen style to Javadoc.

Browse Source 
Changes the start tag of the comments from /*! to /** in order to comply
with the Javadoc commenting style.

Change-Id: Ie6c46f47ee0a7dd6be9788830620dd1c7ee51159
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero 2015-06-26 12:42:00 -05:00 committed by Anas Nashif
parent 4e83dac6e0
commit d35ee355f4
12 changed files with 65 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
doc/doxygen/doxygen_guidelines.rst
View File

@ -3,8 +3,8 @@
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,
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.
@ -13,10 +13,10 @@ 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.
These simple rules apply to all the code that you wish to include in the
documentation:
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 and end a comment block with :literal:`/**` and :literal:`*/`
#. Use \@ for all Doxygen special commands.
@ -28,14 +28,15 @@ documentation:
.. important::
Always use :literal:`/*!` This is a comment. :literal:`*/` if that comment should
become part of the documentation.
Use :literal:`/*` This comment won't appear in the documentation :literal:`*/` for
comments that you want in the code but not in the documentation.
Always use :literal:`/**` This is a comment. :literal:`*/` if that
comment should become part of the documentation.
Use :literal:`/*` This comment won't appear in the documentation :
literal:`*/` for comments that you want in the code but not in the
documentation.
.. toctree::
:maxdepth: 2
doxygen_guidelines_files.rst
doxygen_guidelines_functions.rst
doxygen_guidelines_variables.rst

6
doc/doxygen/doxygen_guidelines_defines.rst
View File

@ -22,7 +22,7 @@ Full template:
.. code-block:: c
/*! @def name_of_define
/** @def name_of_define
@brief Brief description of the define.
@ -36,7 +36,7 @@ Simplified template:
.. code-block:: c
/*!
/**
Brief description of the define.
Multiple lines describing in detail what is the
@ -71,6 +71,6 @@ Incorrect:
:linenos:
Observe that the comment does not start with
:literal:`/*!` and therefore Doxygen will ignore it.
:literal:`/**` and therefore Doxygen will ignore it.
The comment is ambiguous; it could apply to either the define or the #if.

6
doc/doxygen/doxygen_guidelines_functions.rst
View File

@ -22,7 +22,7 @@ Full template:
.. code-block:: c
/*!
/**
* @brief Short description of my_function().
*
* @details Longer multi-paragraph description.
@ -46,7 +46,7 @@ Simplified template:
.. code-block:: c
/*!
/**
* Short description of my_function().
*
* Longer multi-paragraph description.
@ -107,7 +107,7 @@ Take the more complex function hello_loop():
The function parameters have been documented using the correct Doxygen
command but notice line 1. The comment block was not started with
:literal:`/*!` and therefore Doxygen won't parse it correctly.
:literal:`/**` and therefore Doxygen won't parse it correctly.
The parameters have been documented using the \\param command. This is
equivalent to using @param but incorrect according to these guidelines.

2
doc/doxygen/doxygen_guidelines_structs.rst
View File

@ -34,7 +34,7 @@ Correct:
:linenos:
Make sure to start every comment with
:literal:`/*!` and end it with :literal:`*/`. Every comment must start
:literal:`/**` and end it with :literal:`*/`. Every comment must start
with a capital letter and end with a period.
Doxygen requires that line 6 is left blank. Ensure a blank line

4
doc/doxygen/doxygen_guidelines_typedefs.rst
View File

@ -16,7 +16,7 @@ what type they are referencing.
.. code-block:: c
/*! Brief description with the type that is being used and why. */
/** Brief description with the type that is being used and why. */
typedef int t_ie;
No further explanation is needed regarding the type even if it is
@ -51,6 +51,6 @@ Incorrect:
The comments on lines 3 and 4 offer little insight into the code's
behavior. Furthermore, they do not start with
:literal:`/*!` and end with :literal:`*/`. Doxygen won't add the
:literal:`/**` and end with :literal:`*/`. Doxygen won't add the
information to the documentation nor link it properly to the complex
type documentation.

4
doc/doxygen/doxygen_guidelines_variables.rst
View File

@ -15,7 +15,7 @@ Variable Comment Template
.. code-block:: c
/*! Brief description of singificant_variable's purpose. */
/** Brief description of singificant_variable's purpose. */
int significant_variable;
Variable Documentation Examples
@ -60,7 +60,7 @@ Variables outside of functions have to be documented as well.
:linenos:
As you can see the syntax of the comment does not change. Always start
the comment with :literal:`/*!` and end it with :literal:`*/`. Remember
the comment with :literal:`/**` and end it with :literal:`*/`. Remember
to begin with a capital letter and end with a period, even if the
comment is only a sentence fragment.

6
doc/doxygen/ex_struct_pre.c
View File

@ -1,11 +1,11 @@
/*! @brief Brief description of struct pre.
/** @brief Brief description of struct pre.
*
* Detailed description of struct pre. Optional
* */
struct pre {
/*! Variable g brief description. */
/** Variable g brief description. */
int g;
/*! Variable h brief description. */
/** Variable h brief description. */
int h;
};

41
doc/doxygen/hello_commented.c
View File

@ -1,7 +1,7 @@
/*! @file
/** @file
@brief Hello World Demo
A Hello World demo for the Nanokernel and the Microkernel.
A Hello World demo for the Nanokernel and the Microkernel.
*/
/*
@ -34,22 +34,22 @@
* POSSIBILITY OF SUCH DAMAGE.
*/
/*! CONFIG_MICROKERNEL
/** CONFIG_MICROKERNEL
The microkernel hello world demo has two tasks that use semaphores
and sleeps to take turns printing a greeting message at a
and sleeps to take turns printing a greeting message at a
controlled rate.*/
/*! #else || CONFIG_NANOKERNEL
/** #else || CONFIG_NANOKERNEL
* The nanokernel hello world demo has a task and a fiber that use
* semaphores and timers to take turns printing a greeting message at
* a controlled rate.
*/
/*!
/**
@def SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
@brief Compute equivalence in ticks.
*/
/*!
/**
@def SLEEPTIME
@brief Specify delay between greetings (in ms).
*/
@ -67,15 +67,15 @@
#include <zephyr.h>
#define SLEEPTIME 500
#define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
#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.
-# Waits, then lets another task run.
@param taskname The task's identification string.
@param mySem The task's semaphore.
@ -94,7 +94,7 @@ void helloLoop(const char *taskname, ksem_t mySem, ksem_t otherSem)
}
}
/*!
/**
@brief Exchanges Hello messages with taskB.
@details
@ -109,7 +109,7 @@ void taskA(void)
helloLoop (__FUNCTION__, TASKASEM, TASKBSEM); /* Action 2 */
}
/*!
/**
@brief Exchanges Hello messages with taskA.
Actions:
@ -120,26 +120,26 @@ void taskB(void)
helloLoop (__FUNCTION__, TASKBSEM, TASKASEM); /* Action 1 */
}
#else
#else
#include <nanokernel.h>
#include <nanokernel/cpu.h>
#define SLEEPTIME 500
#define SLEEPTIME 500
#define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
#define STACKSIZE 2000
/*! Declares a stack for a fiber with a size of 2000.*/
/** Declares a stack for a fiber with a size of 2000.*/
char fiberStack[STACKSIZE];
/*! Declares a nanokernel semaphore for a task. */
/** Declares a nanokernel semaphore for a task. */
struct nano_sem nanoSemTask;
/*! Declares a nanokernel semaphore for a fiber.*/
/** Declares a nanokernel semaphore for a fiber.*/
struct nano_sem nanoSemFiber;
/*!
/**
@brief Defines the turns taken by the tasks in the fiber.
Actions:
@ -169,7 +169,7 @@ void fiberEntry(void) {
}
}
/*!
/**
@brief Implements the Hello demo.
Actions:
@ -199,5 +199,4 @@ void main(void) {
}
}
#endif
#endif

10
doc/doxygen/irq_test_common_commented.h
View File

@ -65,10 +65,10 @@ Interrupt stuff, abstracted across CPU architectures.
#endif /* NUM_SW_IRQS >= 2 */
#endif
/*! Declares a void-void function pointer to test the ISR. */
/** Declares a void-void function pointer to test the ISR. */
typedef void (*vvfn)(void);
/*! Declares a void-void_pointer function pointer to test the ISR. */
/** Declares a void-void_pointer function pointer to test the ISR. */
typedef void (*vvpfn)(void *);
#if defined(CONFIG_X86_32)
@ -113,13 +113,13 @@ static inline void sw_isr_trigger_1(void)
#endif /* CONFIG_CPU_CORTEX_M */
#endif
/*! Defines the ISR initialization information. */
/** Defines the ISR initialization information. */
struct isrInitInfo
{
/*! Declares the void-void function pointer for the ISR. */
/** Declares the void-void function pointer for the ISR. */
vvpfn isr[2];
/*! Declares a space for the information. */
/** Declares a space for the information. */
void *arg[2];
};

4
doc/doxygen/phil_commented.h
View File

@ -1,4 +1,4 @@
/*! @file
/** @file
* @brief Dining philosophers header file.
*
* Collects the includes and defines needed to implement the dining philosophers
@ -43,7 +43,7 @@
#include <misc/printk.h>
#endif
/*!
/**
@def N_PHILOSOPHERS
@brief Defines the number of philosophers.

20
doc/doxygen/phil_fiber_commented.c
View File

@ -1,4 +1,4 @@
/*! @file
/** @file
* @brief Solution to the dining philosophers problem using fibers.
*/
@ -69,7 +69,7 @@ kmutex_t forks[] = { forkMutex0, forkMutex1, forkMutex2, forkMutex3, forkMutex4,
forkMutex5 };
#endif
/*!
/**
* @brief Prints a philosopher's state.
*
* @param id A philosopher's ID.
@ -83,7 +83,7 @@ static void myPrint(int id,
PRINTF("\x1b[%d;%dHPhilosopher %d %s\n", id + 1, 1, id, str);
}
/*!
/**
* @brief Waits for a number of ticks to elapse.
*
* @param ticks Number of ticks to delay.
@ -103,7 +103,7 @@ static void myDelay(int ticks
#endif
}
/*!
/**
* @brief Entry point to a philosopher's thread.
*
* @details This routine runs as a task in the microkernel environment
@ -117,23 +117,23 @@ static void myDelay(int ticks
*/
void philEntry(void) {
#ifdef CONFIG_NANOKERNEL
/*! Declares a fork for the nanokernel. */
/** Declares a fork for the nanokernel. */
struct nano_sem *f1;
/*! Declares a second fork for the nanokernel. */
/** Declares a second fork for the nanokernel. */
struct nano_sem *f2;
#else
/*! Declares a fork for the microkernel. */
/** Declares a fork for the microkernel. */
kmutex_t f1;
kmutex_t f2;
#endif
/*! Declares the current philosopher's ID. */
/** Declares the current philosopher's ID. */
static int myId;
/*! Declares an interrupt lock level.*/
/** Declares an interrupt lock level.*/
int pri = irq_lock();
/*! Declares the next philosopher's ID. */
/** Declares the next philosopher's ID. */
int id = myId++;
irq_unlock(pri);

6
doc/doxygen/phil_task_commented.c
View File

@ -1,4 +1,4 @@
/*! @file
/** @file
* @brief An implementation of a solution to the dining philosophers problem
* for both the nano- and microkernel.
*
@ -67,7 +67,7 @@ struct nano_sem forks[N_PHILOSOPHERS];//!< Declares global semaphore forks for t
#ifdef CONFIG_NANOKERNEL
/*!
/**
* @brief The nanokernel entry point.
*
* Actions:
@ -102,7 +102,7 @@ int main (void)
#else
/*!
/**
* @brief Starts the dining philosophers demo of the microkernel.
*
* This function starts the dining philosophers demo and