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 <[email protected]> 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 <[email protected]> >> >> Signed-off-by: Christophe Milard <[email protected]> >> Signed-off-by: Mike Holmes <[email protected]> >> --- >> 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. >> + */ >> > >
