Clarify the guide lines around using doxygen to document the ODP API. Signed-off-by: Mike Holmes <[email protected]> --- doxygen_guide_lines.dox | 54 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 doxygen_guide_lines.dox
diff --git a/doxygen_guide_lines.dox b/doxygen_guide_lines.dox new file mode 100644 index 0000000..f76da5a --- /dev/null +++ b/doxygen_guide_lines.dox @@ -0,0 +1,54 @@ +/* Copyright (c) 2014, Linaro Limited + + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + +@page doxygen_guide_lines Doxygen Guide Lines + +@tableofcontents + +@section doxygen_introduction Introduction +ODP uses doxygen http://www.stack.nl/~dimitri/doxygen/ to document the public API. +This guide lists the ODP best practices for using the doxygen features. + +@section function_parameters Function Parameters + +Every parameter to a function must be documented with the \@param tag. +The direction indicators should be used, [in],[out] and [in,out] with the following guide lines for pointer arguments:- + - [in] Can generally be dropped, but indicates that data pre populated at the pointed to location is required by the function + - [out] Indicates that the function will populate the pointed to location with a result + - [in,out] Indicates that the location contains information used by the function, and it will populate the location with a result + +@section function_return Function return arguments + +Every function return other than void will be documented with \@return or \@retval with the following guide lines:- + - \@retval is used where a specific value is returned for a case or range of cases. + - For example retval would be used to specify that success is 0 and a failure to open a file returns -1 + @verbatim + @retval 0 on success + @retval -1 when the file cannot be opened + @endverbatim + - \@return is used where a range is described, but no specific returned value + - For example where a pointer to a structure is specified + @verbatim @return A pointer to the new structure @endverbatim + +In combination these may be used to detail specific return values that the implementation is expected to check for and document the general case. + +@verbatim +@return A pointer to the new structure +@retval NULL If the input arguments to the function are invalid +@retval NULL If the memory cannot be allocated +@endverbatim + +@section test_cases Documenting Test Cases +The \@retval tag has specific meaning for the test cases, an implementation of the ODP API is expected to conform to the behaviour specified by the retvals and unit tests should check that the behaviour exists. +In the above example test cases should try to prove that invalid input arguments or a failure to allocate memory return NULL. + +@section doxygen_errno Documenting errno +The \@retval tag also have specific meaning to the use of errno, these cases are the ones that should set errno to detail the specific reason, for example in the case above NULL is returned to indicate failure and errno should indicate which of the two failing cases has occurred. + +*/ -- 2.1.0 _______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
