On Wed, Dec 17, 2014 at 2:12 PM, Mike Holmes <[email protected]> wrote: > > Clarify the guide lines around using doxygen to document the ODP API. > > Signed-off-by: Mike Holmes <[email protected]> >
Reviewed-by: Bill Fischofer <[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
