Applied. On 2014-12-17 15:12, Mike Holmes wrote: > 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
_______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
