// ***  Select one of the comment styles below for functions ***

// ***********************************************************************
// *** FIRST FORM FOR FUNCTIONS 
// *** (using @param list in header comments)*****************************
//************************************************************************

/*!
 * @brief Add a constant to ever element of an array
 * 
 * Example function that adds a number to every element of an input array.
 * This detailed description can be used to spell out exactly what will 
 * happen when the function is called.  Every function header declaration
 * should completely describe the function interface, so that the function 
 * could be used by anyone without access to the actual implementation
 * code.
 * 
 * All input and output parameters must be documented, and if the function 
 * returns a value, the return quantity should be described.  
 * 
 * @param[in,out] ptr    Pointer to an array of floats to be operated upon
 * @param[in]     value  The number which will be added to each element of 
 *                       the array @a ptr[i]
 * @param[in]     length The number of elements in the array at @a ptr.
 * 
 * @returns	 On return, all elements of the the input 
 *               array @a ptr[i] are incremented by @a value.  
 *               The function returns 0 on success, and non-zero on
 *               failure.
 */
int add_value(	
    float  *ptr,    // Array location
    float  value,   // Increment value
    int length);    // Length of the array



// ***********************************************************************
// *** ALTERNATIVE FORM FOR FUNCTIONS 
// *** (using inline comments for function arguments)
// ***********************************************************************

/*!
 * @brief Add a constant to ever element of an array
 * 
 * Alternative (equivalent?) format for the above function declaration: 
 * Describe the parameters inline as they are listed in the actual
 * declaration.  You can use the standard C comment style, or the C++
 * inline comment style.
 * 
 * All input and output parameters must be documented, and if the function 
 * returns a value, the return quantity should be described.  
 * 
 * @returns	 On return, all elements of the the input 
 *               array @a ptr[i] are incremented by @a value.  
 *               The function returns 0 on success, and non-zero on
 *               failure.
 */
int add_value(	
    float  *ptr,    //!< [in,out] Pointer to an array of floats to be 
                    //!< operated upon
    float  value,   /*!< [in] The number which will be added to each
                         element of  the array  @a ptr[i]. */ 
    int length);    /*!< [in] The number of elements in the array 
                         at @a ptr. */