| Message ID | 1470410831-21571-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | New |
| Headers | show |
Hello Christophe,
I'm still not sure if that is good path for documentation. Mixing c code
and doxygen might be not good.
$(top_srcdir)/platform/${with_platform}/include/odp/api/*.dox
Why not to put it under ./doc ?
Also it looks like we need ./doc/linux-generic/ for everything
linux-generic specific. So that other platforms
can pull from us with out breaking their paths.
Maxim.
On 08/05/16 18:27, Mike Holmes wrote:
> From: Christophe Milard <christophe.milard@linaro.org>
>
> Signed-off-by: Christophe Milard <christophe.milard@linaro.org>
> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> ---
> v2
> Added the new file to the distribution in a generic way (maxim)
>
>
> Do we want to put additional documentation in the DOC dir or in with the platform
> specific header files as Christophe has done initially in this patch ?
>
> I see pros to both.
> In the include dir is where a coder who does not look at docs will find it,
> however generally we put dox files in the DOC dir
>
> I am leaning towards case one as the most helpful to a common case where docs
> are not consulted.
>
>
> doc/platform-api-guide/Makefile.am | 7 +++-
> .../include/odp/api/platform_specific.dox | 46 ++++++++++++++++++++++
> 2 files changed, 52 insertions(+), 1 deletion(-)
> create mode 100644 platform/linux-generic/include/odp/api/platform_specific.dox
>
> diff --git a/doc/platform-api-guide/Makefile.am b/doc/platform-api-guide/Makefile.am
> index a04c254..a3c7f14 100644
> --- a/doc/platform-api-guide/Makefile.am
> +++ b/doc/platform-api-guide/Makefile.am
> @@ -1,5 +1,10 @@
> +#If additional documentation is added in the platform include directory but it is
> +#not in a .h file, it must be included here as an extra part of the distribution
> +
> EXTRA_DIST = \
> - Doxyfile
> + Doxyfile \
> + $(top_srcdir)/platform/${with_platform}/include/odp/api/*.dox
> +
>
> clean-local:
> rm -rf output
> diff --git a/platform/linux-generic/include/odp/api/platform_specific.dox b/platform/linux-generic/include/odp/api/platform_specific.dox
> new file mode 100644
> index 0000000..e116ec6
> --- /dev/null
> +++ b/platform/linux-generic/include/odp/api/platform_specific.dox
> @@ -0,0 +1,46 @@
> +/* Copyright (c) 2016, Linaro Limited
> + * All rights reserved
> + *
> + * SPDX-License-Identifier: BSD-3-Clause
> + */
> +
> +/**
> +* @file platform_specific.dox
> +* extra linux-generic documentation
> +*/
> +
> +/** @addtogroup odp_thread
> + * @par ODP thread
> + * In this ODP implementation an odp thread is either:
> + * - a linux process descendant (or same as) the odp instantiation process.
> + * - a pthread 'member' of a linux process descendant (or same as) the odp
> + * instantiation process.
> + */
> +
> +/**
> + * @fn odp_init_local(odp_instance_t instance, odp_thread_type_t thr_type)
> + * @note In this ODP implementation odpthreads have to be
> + * processes descendant of (or same as) the ODP
> + * instantiation process, or pthreads 'member' of such
> + * processes.
> + * @note As ODP instantiation processes cannot be descendants
> + * of each others, the instance parameter provided
> + * to odp_init_local() is actually fully defined by these
> + * requirements: It has to be the value returned by the
> + * unique call to odp_init_global() made by one single
> + * acsendant of the current process.
> + */
> +
> +/**
> + * @fn odp_init_global(odp_instance_t *instance,
> + * const odp_init_t *params,
> + * const odp_platform_init_t *platform_params)
> + * @note This ODP implementation supports mupliple instances of ODP
> + * (i.e. multiple call to odp_init_global()) with the following
> + * restrictions:
> + * @note -Different ODP instances cannot share the same instantiation
> + * process. In other words, a single process may
> + * only call odp_init_global() once.
> + * @note -Different ODP instantiation processes cannot be descendant of
> + * each other.
> + */
I would also prefer to see this under a doc directory, even if at present that directory contains only a single file. It's jarring to see this mixed in with a bunch of .h files. On Fri, Aug 5, 2016 at 10:53 AM, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: > Hello Christophe, > > I'm still not sure if that is good path for documentation. Mixing c code > and doxygen might be not good. > > $(top_srcdir)/platform/${with_platform}/include/odp/api/*.dox > > Why not to put it under ./doc ? > > Also it looks like we need ./doc/linux-generic/ for everything > linux-generic specific. So that other platforms > can pull from us with out breaking their paths. > > Maxim. > > > > On 08/05/16 18:27, Mike Holmes wrote: > >> From: Christophe Milard <christophe.milard@linaro.org> >> >> Signed-off-by: Christophe Milard <christophe.milard@linaro.org> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> --- >> v2 >> Added the new file to the distribution in a generic way (maxim) >> >> >> Do we want to put additional documentation in the DOC dir or in with the >> platform >> specific header files as Christophe has done initially in this patch ? >> >> I see pros to both. >> In the include dir is where a coder who does not look at docs will find >> it, >> however generally we put dox files in the DOC dir >> >> I am leaning towards case one as the most helpful to a common case where >> docs >> are not consulted. >> >> >> doc/platform-api-guide/Makefile.am | 7 +++- >> .../include/odp/api/platform_specific.dox | 46 >> ++++++++++++++++++++++ >> 2 files changed, 52 insertions(+), 1 deletion(-) >> create mode 100644 platform/linux-generic/include >> /odp/api/platform_specific.dox >> >> diff --git a/doc/platform-api-guide/Makefile.am >> b/doc/platform-api-guide/Makefile.am >> index a04c254..a3c7f14 100644 >> --- a/doc/platform-api-guide/Makefile.am >> +++ b/doc/platform-api-guide/Makefile.am >> @@ -1,5 +1,10 @@ >> +#If additional documentation is added in the platform include directory >> but it is >> +#not in a .h file, it must be included here as an extra part of the >> distribution >> + >> EXTRA_DIST = \ >> - Doxyfile >> + Doxyfile \ >> + $(top_srcdir)/platform/${with_platform}/include/odp/api/*.do >> x >> + >> clean-local: >> rm -rf output >> diff --git a/platform/linux-generic/include/odp/api/platform_specific.dox >> b/platform/linux-generic/include/odp/api/platform_specific.dox >> new file mode 100644 >> index 0000000..e116ec6 >> --- /dev/null >> +++ b/platform/linux-generic/include/odp/api/platform_specific.dox >> @@ -0,0 +1,46 @@ >> +/* Copyright (c) 2016, Linaro Limited >> + * All rights reserved >> + * >> + * SPDX-License-Identifier: BSD-3-Clause >> + */ >> + >> +/** >> +* @file platform_specific.dox >> +* extra linux-generic documentation >> +*/ >> + >> +/** @addtogroup odp_thread >> + * @par ODP thread >> + * In this ODP implementation an odp thread is either: >> + * - a linux process descendant (or same as) the odp instantiation >> process. >> + * - a pthread 'member' of a linux process descendant (or same as) the >> odp >> + * instantiation process. >> + */ >> + >> +/** >> + * @fn odp_init_local(odp_instance_t instance, odp_thread_type_t >> thr_type) >> + * @note In this ODP implementation odpthreads have to be >> + * processes descendant of (or same as) the ODP >> + * instantiation process, or pthreads 'member' of >> such >> + * processes. >> + * @note As ODP instantiation processes cannot be >> descendants >> + * of each others, the instance parameter provided >> + * to odp_init_local() is actually fully defined by >> these >> + * requirements: It has to be the value returned by >> the >> + * unique call to odp_init_global() made by one >> single >> + * acsendant of the current process. >> + */ >> + >> +/** >> + * @fn odp_init_global(odp_instance_t *instance, >> + * const odp_init_t *params, >> + * const odp_platform_init_t *platform_params) >> + * @note This ODP implementation supports mupliple instances of ODP >> + * (i.e. multiple call to odp_init_global()) with the >> following >> + * restrictions: >> + * @note -Different ODP instances cannot share the same >> instantiation >> + * process. In other words, a single process may >> + * only call odp_init_global() once. >> + * @note -Different ODP instantiation processes cannot be >> descendant of >> + * each other. >> + */ >> > >
On 5 August 2016 at 11:53, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: > Hello Christophe, > > I'm still not sure if that is good path for documentation. Mixing c code > and doxygen might be not good. > > $(top_srcdir)/platform/${with_platform}/include/odp/api/*.dox > > Why not to put it under ./doc ? > It cant just be under the top level, but /git/odp/doc/platform-api-guide - I could buy into that for now. However remember that in the future there maybe be multiple platforms in a repo each with different platform specifics so then we will need to replicate the platform include structure for the docs if they are not just in the include structure. > > Also it looks like we need ./doc/linux-generic/ for everything > linux-generic specific. So that other platforms > can pull from us with out breaking their paths. We dont know if they will reuse linux generic in anyway at all so I dont think we should add that, or I missed your intent. > > > Maxim. > > > > On 08/05/16 18:27, Mike Holmes wrote: > >> From: Christophe Milard <christophe.milard@linaro.org> >> >> Signed-off-by: Christophe Milard <christophe.milard@linaro.org> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> --- >> v2 >> Added the new file to the distribution in a generic way (maxim) >> >> >> Do we want to put additional documentation in the DOC dir or in with the >> platform >> specific header files as Christophe has done initially in this patch ? >> >> I see pros to both. >> In the include dir is where a coder who does not look at docs will find >> it, >> however generally we put dox files in the DOC dir >> >> I am leaning towards case one as the most helpful to a common case where >> docs >> are not consulted. >> >> >> doc/platform-api-guide/Makefile.am | 7 +++- >> .../include/odp/api/platform_specific.dox | 46 >> ++++++++++++++++++++++ >> 2 files changed, 52 insertions(+), 1 deletion(-) >> create mode 100644 platform/linux-generic/include >> /odp/api/platform_specific.dox >> >> diff --git a/doc/platform-api-guide/Makefile.am >> b/doc/platform-api-guide/Makefile.am >> index a04c254..a3c7f14 100644 >> --- a/doc/platform-api-guide/Makefile.am >> +++ b/doc/platform-api-guide/Makefile.am >> @@ -1,5 +1,10 @@ >> +#If additional documentation is added in the platform include directory >> but it is >> +#not in a .h file, it must be included here as an extra part of the >> distribution >> + >> EXTRA_DIST = \ >> - Doxyfile >> + Doxyfile \ >> + $(top_srcdir)/platform/${with_platform}/include/odp/api/*.do >> x >> + >> clean-local: >> rm -rf output >> diff --git a/platform/linux-generic/include/odp/api/platform_specific.dox >> b/platform/linux-generic/include/odp/api/platform_specific.dox >> new file mode 100644 >> index 0000000..e116ec6 >> --- /dev/null >> +++ b/platform/linux-generic/include/odp/api/platform_specific.dox >> @@ -0,0 +1,46 @@ >> +/* Copyright (c) 2016, Linaro Limited >> + * All rights reserved >> + * >> + * SPDX-License-Identifier: BSD-3-Clause >> + */ >> + >> +/** >> +* @file platform_specific.dox >> +* extra linux-generic documentation >> +*/ >> + >> +/** @addtogroup odp_thread >> + * @par ODP thread >> + * In this ODP implementation an odp thread is either: >> + * - a linux process descendant (or same as) the odp instantiation >> process. >> + * - a pthread 'member' of a linux process descendant (or same as) the >> odp >> + * instantiation process. >> + */ >> + >> +/** >> + * @fn odp_init_local(odp_instance_t instance, odp_thread_type_t >> thr_type) >> + * @note In this ODP implementation odpthreads have to be >> + * processes descendant of (or same as) the ODP >> + * instantiation process, or pthreads 'member' of >> such >> + * processes. >> + * @note As ODP instantiation processes cannot be >> descendants >> + * of each others, the instance parameter provided >> + * to odp_init_local() is actually fully defined by >> these >> + * requirements: It has to be the value returned by >> the >> + * unique call to odp_init_global() made by one >> single >> + * acsendant of the current process. >> + */ >> + >> +/** >> + * @fn odp_init_global(odp_instance_t *instance, >> + * const odp_init_t *params, >> + * const odp_platform_init_t *platform_params) >> + * @note This ODP implementation supports mupliple instances of ODP >> + * (i.e. multiple call to odp_init_global()) with the >> following >> + * restrictions: >> + * @note -Different ODP instances cannot share the same >> instantiation >> + * process. In other words, a single process may >> + * only call odp_init_global() once. >> + * @note -Different ODP instantiation processes cannot be >> descendant of >> + * each other. >> + */ >> > > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs "Work should be fun and collaborative, the rest follows"
diff --git a/doc/platform-api-guide/Makefile.am b/doc/platform-api-guide/Makefile.am index a04c254..a3c7f14 100644 --- a/doc/platform-api-guide/Makefile.am +++ b/doc/platform-api-guide/Makefile.am @@ -1,5 +1,10 @@ +#If additional documentation is added in the platform include directory but it is +#not in a .h file, it must be included here as an extra part of the distribution + EXTRA_DIST = \ - Doxyfile + Doxyfile \ + $(top_srcdir)/platform/${with_platform}/include/odp/api/*.dox + clean-local: rm -rf output diff --git a/platform/linux-generic/include/odp/api/platform_specific.dox b/platform/linux-generic/include/odp/api/platform_specific.dox new file mode 100644 index 0000000..e116ec6 --- /dev/null +++ b/platform/linux-generic/include/odp/api/platform_specific.dox @@ -0,0 +1,46 @@ +/* Copyright (c) 2016, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** +* @file platform_specific.dox +* extra linux-generic documentation +*/ + +/** @addtogroup odp_thread + * @par ODP thread + * In this ODP implementation an odp thread is either: + * - a linux process descendant (or same as) the odp instantiation process. + * - a pthread 'member' of a linux process descendant (or same as) the odp + * instantiation process. + */ + +/** + * @fn odp_init_local(odp_instance_t instance, odp_thread_type_t thr_type) + * @note In this ODP implementation odpthreads have to be + * processes descendant of (or same as) the ODP + * instantiation process, or pthreads 'member' of such + * processes. + * @note As ODP instantiation processes cannot be descendants + * of each others, the instance parameter provided + * to odp_init_local() is actually fully defined by these + * requirements: It has to be the value returned by the + * unique call to odp_init_global() made by one single + * acsendant of the current process. + */ + +/** + * @fn odp_init_global(odp_instance_t *instance, + * const odp_init_t *params, + * const odp_platform_init_t *platform_params) + * @note This ODP implementation supports mupliple instances of ODP + * (i.e. multiple call to odp_init_global()) with the following + * restrictions: + * @note -Different ODP instances cannot share the same instantiation + * process. In other words, a single process may + * only call odp_init_global() once. + * @note -Different ODP instantiation processes cannot be descendant of + * each other. + */