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


Ignore:
Timestamp:
Oct 5, 2009, 6:03:20 PM (10 years ago)
Author:
Sh
Comment:

Added "Best Practice" section.

Legend:

Unmodified
Added
Removed
Modified
  • Developer/Coding/Doxygen

    v3 v4  
    11= Doxygen Recommendations =
    22
     3=  Best Practice  =
     4
     5
     6 *  Do not use ''@param''.  Instead use ''@a name'' to document function parameters.
     7 *  Do not use ''@return''.
     8 *  Use ''@retval'' to document return status codes.
     9 *  Do not write documentation for trivial functions.
     10 *  Use groups and arrange them in a hierarchy.
     11 *  Put every file into at least one group.
     12 *  Do not use ''@note''.
     13 *  Use dot comments for state diagrams.
     14 *  Do not repeat documentation, use ''@see'' for example.
     15=  Header File Example  =
     16
     17{{{
     18/**
     19 * @file
     20 *
     21 * @ingroup FlipFlop
     22 *
     23 * @brief Flip-Flop API.
     24 */
     25
     26/*
     27 * Copyright (c) YYYY Author.
     28 *
     29 * The license and distribution terms for this file may be
     30 * found in the file LICENSE in this distribution or at
     31 * http://www.rtems.com/license/LICENSE.
     32 *
     33 * $Id$
     34 */
     35
     36#ifndef FLIP_FLOP_H
     37#define FLIP_FLOP_H
     38
     39#include <rtems.h>
     40
     41#ifdef __cplusplus
     42extern "C" {
     43#endif /* __cplusplus */
     44
     45/**
     46 * @defgroup FlipFlop Flip-Flop
     47 *
     48 * @brief Simple Flip-Flop state machine.
     49 *
     50 * @dot
     51 *   digraph {
     52 *     start [label="START"];
     53 *     flip [label="FLIP"];
     54 *     flop [label="FLOP"];
     55 *     flip -> flop [label="flop()", URL="\ref flop"];
     56 *     flop -> flip [label="flip()", URL="\ref flip"];
     57 *     start -> flip
     58 *       [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"];
     59 *     start -> flop
     60 *       [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"];
     61 *     flip -> start
     62 *       [label="flip_flop_restart()", URL="\ref flip_flop_restart"];
     63 *   }
     64 * @enddot
     65 *
     66 * @{
     67 */
     68
     69typedef enum {
     70  START = 0,
     71  FLIP,
     72  FLOP
     73} flip_flop_state;
     74
     75/**
     76 * @name Flip-Flop Maintanance
     77 *
     78 * @{
     79 */
     80
     81/**
     82 * @brief Initializes the flip-flop in the state @a state.
     83 *
     84 * @retval RTEMS_SUCCESSFUL Successfully initialized.
     85 * @retval RTEMS_INCORRECT_STATE Flip-flop not in start state.
     86 */
     87rtems_status_code flip_flop_initialize(flip_flop_state state);
     88
     89/**
     90 * @brief Restarts the flip-flop.
     91 *
     92 * @retval RTEMS_SUCCESSFUL Successfully restarted.
     93 * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state.
     94 */
     95rtems_status_code flip_flop_restart(void);
     96
     97flip_flop_state flip_flop_current_state(void);
     98
     99/** @} */
     100
     101/**
     102 * @name Flip-Flop Usage
     103 *
     104 * @{
     105 */
     106
     107/**
     108 * @brief Flip operation.
     109 *
     110 * @retval RTEMS_SUCCESSFUL Flipped successfully.
     111 * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation.
     112 */
     113rtems_status_code flip(void);
     114
     115/**
     116 * @brief Flop operation.
     117 *
     118 * @retval RTEMS_SUCCESSFUL Flopped successfully.
     119 * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation.
     120 */
     121rtems_status_code flop(void);
     122
     123/** @} */
     124
     125/** @} */
     126
     127#ifdef __cplusplus
     128}
     129#endif /* __cplusplus */
     130
     131#endif /* FLIP_FLOP_H */
     132}}}
     133=  Source File Example  =
     134
     135{{{
     136/**
     137 * @file
     138 *
     139 * @ingroup FlipFlop
     140 *
     141 * @brief Flip-Flop implementation.
     142 */
     143
     144/*
     145 * Copyright (c) YYYY Author.
     146 *
     147 * The license and distribution terms for this file may be
     148 * found in the file LICENSE in this distribution or at
     149 * http://www.rtems.com/license/LICENSE.
     150 *
     151 * $Id$
     152 */
     153
     154#include "flip-flop.h"
     155
     156static flip_flop_state current_state;
     157
     158rtems_status_code flip_flop_initialize(flip_flop_state state)
     159{
     160  if (current_state == START) {
     161    current_state = state;
     162
     163    return RTEMS_SUCCESSFUL;
     164  } else {
     165    return RTEMS_INCORRECT_STATE;
     166  }
     167}
     168
     169rtems_status_code flip_flop_restart(void)
     170{
     171  if (current_state == FLIP) {
     172    current_state = START;
     173
     174    return RTEMS_SUCCESSFUL;
     175  } else {
     176    return RTEMS_INCORRECT_STATE;
     177  }
     178}
     179
     180flip_flop_state flip_flop_current_state(void)
     181{
     182  return current_state;
     183}
     184
     185rtems_status_code flip(void)
     186{
     187  if (current_state == FLOP) {
     188    current_state = FLIP;
     189
     190    return RTEMS_SUCCESSFUL;
     191  } else {
     192    return RTEMS_INCORRECT_STATE;
     193  }
     194}
     195
     196rtems_status_code flop(void)
     197{
     198  if (current_state == FLIP) {
     199    current_state = FLOP;
     200
     201    return RTEMS_SUCCESSFUL;
     202  } else {
     203    return RTEMS_INCORRECT_STATE;
     204  }
     205}
     206}}}
    3207=  Files  =
    4208