| Message ID | 1429559734-22187-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | Accepted |
| Commit | 9abad7f099e5c23ccb26c1042ef64bc80f04a644 |
| Headers | show |
On 20 April 2015 at 21:55, Mike Holmes <mike.holmes@linaro.org> wrote: > If the examples are on the src path they pollute the documentation > with their own declarations. > > The correct mechanism is to declare the examples to be seen in the > documentation in one location that is on the .dox path, and have the > EXAMPLE_PATH locate the actual example code. > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > Reviewed-by: Anders Roxell <anders.roxell@linaro.org> > --- > v3 fix "*" in comments to look like all the other files > > doc/doxygen.cfg | 7 ++++++- > doc/examples.dox | 20 ++++++++++++++++++++ > example/generator/odp_generator.c | 6 ------ > example/packet/odp_pktio.c | 6 ------ > example/timer/odp_timer_test.c | 6 ------ > 5 files changed, 26 insertions(+), 19 deletions(-) > create mode 100644 doc/examples.dox > > diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg > index 4208afa..6283387 100644 > --- a/doc/doxygen.cfg > +++ b/doc/doxygen.cfg > @@ -10,7 +10,12 @@ TYPEDEF_HIDES_STRUCT = NO > EXTRACT_STATIC = YES > SORT_MEMBER_DOCS = NO > WARN_NO_PARAMDOC = YES > -INPUT = $(SRCDIR)/doc $(SRCDIR)/doc/users-guide $(SRCDIR)/include > $(SRCDIR)/platform/linux-generic/include/odp > $(SRCDIR)/platform/$(WITH_PLATFORM)/include/odp $(SRCDIR)/helper/include > $(SRCDIR)/example/packet $(SRCDIR)/example/generator $(SRCDIR)/example/timer > +INPUT = $(SRCDIR)/doc \ > + $(SRCDIR)/doc/users-guide \ > + $(SRCDIR)/include \ > + $(SRCDIR)/platform/linux-generic/include/odp \ > + $(SRCDIR)/platform/$(WITH_PLATFORM)/include/odp \ > + $(SRCDIR)/helper/include > FILE_PATTERNS = *.h odp*.c *.dox > RECURSIVE = YES > SOURCE_BROWSER = YES > diff --git a/doc/examples.dox b/doc/examples.dox > new file mode 100644 > index 0000000..2a7c597 > --- /dev/null > +++ b/doc/examples.dox > @@ -0,0 +1,20 @@ > +/* Copyright (c) 2015, Linaro Limited > + * All rights reserved. > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > + * @example odp_generator.c > + * ODP loopback demo application > + */ > + > +/** > + *@example odp_pktio.c > + * ODP basic packet IO loopback test application > + */ > + > +/** > + * @example odp_timer_test.c > + * ODP timer example application > + */ > diff --git a/example/generator/odp_generator.c > b/example/generator/odp_generator.c > index 2ac0b47..8ae5b29 100644 > --- a/example/generator/odp_generator.c > +++ b/example/generator/odp_generator.c > @@ -4,12 +4,6 @@ > * SPDX-License-Identifier: BSD-3-Clause > */ > > -/** > - * @file > - * > - * @example odp_generator.c ODP loopback demo application > - */ > - > /** enable strtok */ > #define _POSIX_C_SOURCE 200112L > > diff --git a/example/packet/odp_pktio.c b/example/packet/odp_pktio.c > index 61af855..f08d9f4 100644 > --- a/example/packet/odp_pktio.c > +++ b/example/packet/odp_pktio.c > @@ -4,12 +4,6 @@ > * SPDX-License-Identifier: BSD-3-Clause > */ > > -/** > - * @file > - * > - * @example odp_pktio.c ODP basic packet IO loopback test application > - */ > - > #include <stdlib.h> > #include <string.h> > #include <getopt.h> > diff --git a/example/timer/odp_timer_test.c > b/example/timer/odp_timer_test.c > index 6b60ec4..acac580 100644 > --- a/example/timer/odp_timer_test.c > +++ b/example/timer/odp_timer_test.c > @@ -4,12 +4,6 @@ > * SPDX-License-Identifier: BSD-3-Clause > */ > > -/** > - * @file > - * > - * @example odp_timer_test.c ODP timer example application > - */ > - > #include <string.h> > #include <stdlib.h> > > -- > 2.1.0 > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index 4208afa..6283387 100644 --- a/doc/doxygen.cfg +++ b/doc/doxygen.cfg @@ -10,7 +10,12 @@ TYPEDEF_HIDES_STRUCT = NO EXTRACT_STATIC = YES SORT_MEMBER_DOCS = NO WARN_NO_PARAMDOC = YES -INPUT = $(SRCDIR)/doc $(SRCDIR)/doc/users-guide $(SRCDIR)/include $(SRCDIR)/platform/linux-generic/include/odp $(SRCDIR)/platform/$(WITH_PLATFORM)/include/odp $(SRCDIR)/helper/include $(SRCDIR)/example/packet $(SRCDIR)/example/generator $(SRCDIR)/example/timer +INPUT = $(SRCDIR)/doc \ + $(SRCDIR)/doc/users-guide \ + $(SRCDIR)/include \ + $(SRCDIR)/platform/linux-generic/include/odp \ + $(SRCDIR)/platform/$(WITH_PLATFORM)/include/odp \ + $(SRCDIR)/helper/include FILE_PATTERNS = *.h odp*.c *.dox RECURSIVE = YES SOURCE_BROWSER = YES diff --git a/doc/examples.dox b/doc/examples.dox new file mode 100644 index 0000000..2a7c597 --- /dev/null +++ b/doc/examples.dox @@ -0,0 +1,20 @@ +/* Copyright (c) 2015, Linaro Limited + * All rights reserved. + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** + * @example odp_generator.c + * ODP loopback demo application + */ + +/** + *@example odp_pktio.c + * ODP basic packet IO loopback test application + */ + +/** + * @example odp_timer_test.c + * ODP timer example application + */ diff --git a/example/generator/odp_generator.c b/example/generator/odp_generator.c index 2ac0b47..8ae5b29 100644 --- a/example/generator/odp_generator.c +++ b/example/generator/odp_generator.c @@ -4,12 +4,6 @@ * SPDX-License-Identifier: BSD-3-Clause */ -/** - * @file - * - * @example odp_generator.c ODP loopback demo application - */ - /** enable strtok */ #define _POSIX_C_SOURCE 200112L diff --git a/example/packet/odp_pktio.c b/example/packet/odp_pktio.c index 61af855..f08d9f4 100644 --- a/example/packet/odp_pktio.c +++ b/example/packet/odp_pktio.c @@ -4,12 +4,6 @@ * SPDX-License-Identifier: BSD-3-Clause */ -/** - * @file - * - * @example odp_pktio.c ODP basic packet IO loopback test application - */ - #include <stdlib.h> #include <string.h> #include <getopt.h> diff --git a/example/timer/odp_timer_test.c b/example/timer/odp_timer_test.c index 6b60ec4..acac580 100644 --- a/example/timer/odp_timer_test.c +++ b/example/timer/odp_timer_test.c @@ -4,12 +4,6 @@ * SPDX-License-Identifier: BSD-3-Clause */ -/** - * @file - * - * @example odp_timer_test.c ODP timer example application - */ - #include <string.h> #include <stdlib.h>
If the examples are on the src path they pollute the documentation with their own declarations. The correct mechanism is to declare the examples to be seen in the documentation in one location that is on the .dox path, and have the EXAMPLE_PATH locate the actual example code. Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- v3 fix "*" in comments to look like all the other files doc/doxygen.cfg | 7 ++++++- doc/examples.dox | 20 ++++++++++++++++++++ example/generator/odp_generator.c | 6 ------ example/packet/odp_pktio.c | 6 ------ example/timer/odp_timer_test.c | 6 ------ 5 files changed, 26 insertions(+), 19 deletions(-) create mode 100644 doc/examples.dox