On 17 December 2014 at 17:25, Anders Roxell <[email protected]> wrote: > > 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. >
I was not sure there would not be any exceptions to the rule so I left it as generally, but if no one can think of an example I will make that language tighter. > > > + - [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" > > > Will fix > Cheers, > Anders > -- *Mike Holmes* Linaro Sr Technical Manager LNG - ODP
_______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
