[ARCH] add doxygen_guide_lines

Clarify the guide lines around using doxygen to document the ODP API.

Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
---
 doxygen_guide_lines.dox | 54 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 doxygen_guide_lines.dox

On Wed, Dec 17, 2014 at 2:12 PM, Mike Holmes <mike.holmes@linaro.org> wrote:
>
> Clarify the guide lines around using doxygen to document the ODP API.
>
> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
>

Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org>


> ---
>  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
> lng-odp@lists.linaro.org
> http://lists.linaro.org/mailman/listinfo/lng-odp
>

On 17 December 2014 at 21:12, Mike Holmes <mike.holmes@linaro.org> wrote:
> Clarify the guide lines around using doxygen to document the ODP API.
>
> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> ---
>  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

On 17 December 2014 at 17:25, Anders Roxell <anders.roxell@linaro.org>
wrote:
>
> On 17 December 2014 at 21:12, Mike Holmes <mike.holmes@linaro.org> wrote:
> > Clarify the guide lines around using doxygen to document the ODP API.
> >
> > Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> > ---
> >  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
>

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 <mike.holmes@linaro.org>
> ---
>  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
> lng-odp@lists.linaro.org
> http://lists.linaro.org/mailman/listinfo/lng-odp