On 17 December 2014 at 21:12, Mike Holmes <[email protected]> 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
Can anyone think of a case where we need to document @param[in] or can we always drop "[in]"? NOTE: @param[in, out] we need to distinguish like this. > + - [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:- We agreed on putting "return" and/or "retval" in the buffer and/or packets patches. replace or above with "and/or" Cheers, Anders _______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
