Changes between Version 3 and Version 4 of Developer/Coding/Doxygen

Timestamp:

10/05/09 18:03:20 (15 years ago)

Author:

Sh

Comment:

Added "Best Practice" section.

Developer/Coding/Doxygen

@@ -1 +1 @@
 = Doxygen Recommendations =
 
+=  Best Practice  =
+
+
+ *  Do not use ''@param''.  Instead use ''@a name'' to document function parameters.
+ *  Do not use ''@return''.
+ *  Use ''@retval'' to document return status codes.
+ *  Do not write documentation for trivial functions.
+ *  Use groups and arrange them in a hierarchy.
+ *  Put every file into at least one group.
+ *  Do not use ''@note''.
+ *  Use dot comments for state diagrams.
+ *  Do not repeat documentation, use ''@see'' for example.
+=  Header File Example  =
+
+{{{
+/**
+ * @file
+ *
+ * @ingroup FlipFlop
+ *
+ * @brief Flip-Flop API.
+ */
+
+/*
+ * Copyright (c) YYYY Author.
+ *
+ * The license and distribution terms for this file may be
+ * found in the file LICENSE in this distribution or at
+ * http://www.rtems.com/license/LICENSE.
+ *
+ * $Id$
+ */
+
+#ifndef FLIP_FLOP_H
+#define FLIP_FLOP_H
+
+#include <rtems.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+/**
+ * @defgroup FlipFlop Flip-Flop
+ *
+ * @brief Simple Flip-Flop state machine.
+ *
+ * @dot
+ *   digraph {
+ *     start [label="START"];
+ *     flip [label="FLIP"];
+ *     flop [label="FLOP"];
+ *     flip -> flop [label="flop()", URL="\ref flop"];
+ *     flop -> flip [label="flip()", URL="\ref flip"];
+ *     start -> flip
+ *       [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"];
+ *     start -> flop
+ *       [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"];
+ *     flip -> start
+ *       [label="flip_flop_restart()", URL="\ref flip_flop_restart"];
+ *   }
+ * @enddot
+ *
+ * @{
+ */
+
+typedef enum {
+  START = 0,
+  FLIP,
+  FLOP
+} flip_flop_state;
+
+/**
+ * @name Flip-Flop Maintanance
+ *
+ * @{
+ */
+
+/**
+ * @brief Initializes the flip-flop in the state @a state.
+ *
+ * @retval RTEMS_SUCCESSFUL Successfully initialized.
+ * @retval RTEMS_INCORRECT_STATE Flip-flop not in start state.
+ */
+rtems_status_code flip_flop_initialize(flip_flop_state state);
+
+/**
+ * @brief Restarts the flip-flop.
+ *
+ * @retval RTEMS_SUCCESSFUL Successfully restarted.
+ * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state.
+ */
+rtems_status_code flip_flop_restart(void);
+
+flip_flop_state flip_flop_current_state(void);
+
+/** @} */
+
+/**
+ * @name Flip-Flop Usage
+ *
+ * @{
+ */
+
+/**
+ * @brief Flip operation.
+ *
+ * @retval RTEMS_SUCCESSFUL Flipped successfully.
+ * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation.
+ */
+rtems_status_code flip(void);
+
+/**
+ * @brief Flop operation.
+ *
+ * @retval RTEMS_SUCCESSFUL Flopped successfully.
+ * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation.
+ */
+rtems_status_code flop(void);
+
+/** @} */
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#endif /* FLIP_FLOP_H */
+}}}
+=  Source File Example  =
+
+{{{
+/**
+ * @file
+ *
+ * @ingroup FlipFlop
+ *
+ * @brief Flip-Flop implementation.
+ */
+
+/*
+ * Copyright (c) YYYY Author.
+ *
+ * The license and distribution terms for this file may be
+ * found in the file LICENSE in this distribution or at
+ * http://www.rtems.com/license/LICENSE.
+ *
+ * $Id$
+ */
+
+#include "flip-flop.h"
+
+static flip_flop_state current_state;
+
+rtems_status_code flip_flop_initialize(flip_flop_state state)
+{
+  if (current_state == START) {
+    current_state = state;
+
+    return RTEMS_SUCCESSFUL;
+  } else {
+    return RTEMS_INCORRECT_STATE;
+  }
+}
+
+rtems_status_code flip_flop_restart(void)
+{
+  if (current_state == FLIP) {
+    current_state = START;
+
+    return RTEMS_SUCCESSFUL;
+  } else {
+    return RTEMS_INCORRECT_STATE;
+  }
+}
+
+flip_flop_state flip_flop_current_state(void)
+{
+  return current_state;
+}
+
+rtems_status_code flip(void)
+{
+  if (current_state == FLOP) {
+    current_state = FLIP;
+
+    return RTEMS_SUCCESSFUL;
+  } else {
+    return RTEMS_INCORRECT_STATE;
+  }
+}
+
+rtems_status_code flop(void)
+{
+  if (current_state == FLIP) {
+    current_state = FLOP;
+
+    return RTEMS_SUCCESSFUL;
+  } else {
+    return RTEMS_INCORRECT_STATE;
+  }
+}
+}}}
 =  Files  =