[dpdk-dev] [PATCH] doc: add example programs to doxygen api docs

[dpdk-dev] [PATCH] doc: add example programs to doxygen api docs

[John McNamara]

Enable Doxygen parsing of DPDK example files so that the example
code is linked to and from the API docs. This allows the reader
to see examples of API usage in context by following a link.

Signed-off-by: John McNamara <john.mcnamara@intel.com>
---

Notes:

* Here is an example of the sample code/api linkage in use:

  http://www.stack.nl/~dimitri/doxygen/manual/examples/example/html/examples.html
 
* The examples.dox file could be autogenerated from the build system.


doc/api/doxy-api.conf |   6 +-
 doc/api/examples.dox  | 222 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 227 insertions(+), 1 deletion(-)
 create mode 100644 doc/api/examples.dox

diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf
index 15bba16..96a877f 100644
--- a/doc/api/doxy-api.conf
+++ b/doc/api/doxy-api.conf
@@ -60,12 +60,16 @@ INPUT                   = doc/api/doxy-api-index.md \
                           lib/librte_sched \
                           lib/librte_table \
                           lib/librte_timer \
-                          lib/librte_vhost
+                          lib/librte_vhost \
+                          doc/api/examples.dox
 FILE_PATTERNS           = rte_*.h \
                           cmdline.h
 PREDEFINED              = __DOXYGEN__ \
                           __attribute__(x)=
 
+EXAMPLE_PATH            = examples
+EXAMPLE_PATTERNS        = *.c
+EXAMPLE_RECURSIVE       = YES
 OPTIMIZE_OUTPUT_FOR_C   = YES
 ENABLE_PREPROCESSING    = YES
 MACRO_EXPANSION         = YES
diff --git a/doc/api/examples.dox b/doc/api/examples.dox
new file mode 100644
index 0000000..4f0e2bb
--- /dev/null
+++ b/doc/api/examples.dox
@@ -0,0 +1,222 @@
+/**
+@page examples DPDK Example Programs
+
+@example bond/main.c
+
+@example cmdline/commands.c
+
+@example cmdline/main.c
+
+@example cmdline/parse_obj_list.c
+
+@example distributor/main.c
+
+@example dpdk_qat/crypto.c
+
+@example dpdk_qat/main.c
+
+@example ethtool/ethtool-app/ethapp.c
+
+@example ethtool/ethtool-app/main.c
+
+@example ethtool/lib/rte_ethtool.c
+
+@example exception_path/main.c
+
+@example helloworld/main.c
+
+@example ip_fragmentation/main.c
+
+@example ip_pipeline/config_check.c
+
+@example ip_pipeline/config_parse.c
+
+@example ip_pipeline/config_parse_tm.c
+
+@example ip_pipeline/cpu_core_map.c
+
+@example ip_pipeline/init.c
+
+@example ip_pipeline/main.c
+
+@example ip_pipeline/pipeline/pipeline_common_be.c
+
+@example ip_pipeline/pipeline/pipeline_common_fe.c
+
+@example ip_pipeline/pipeline/pipeline_firewall_be.c
+
+@example ip_pipeline/pipeline/pipeline_firewall.c
+
+@example ip_pipeline/pipeline/pipeline_flow_actions_be.c
+
+@example ip_pipeline/pipeline/pipeline_flow_actions.c
+
+@example ip_pipeline/pipeline/pipeline_flow_classification_be.c
+
+@example ip_pipeline/pipeline/pipeline_flow_classification.c
+
+@example ip_pipeline/pipeline/pipeline_master_be.c
+
+@example ip_pipeline/pipeline/pipeline_master.c
+
+@example ip_pipeline/pipeline/pipeline_passthrough_be.c
+
+@example ip_pipeline/pipeline/pipeline_passthrough.c
+
+@example ip_pipeline/pipeline/pipeline_routing_be.c
+
+@example ip_pipeline/pipeline/pipeline_routing.c
+
+@example ip_pipeline/thread.c
+
+@example ip_pipeline/thread_fe.c
+
+@example ip_reassembly/main.c
+
+@example ipv4_multicast/main.c
+
+@example kni/main.c
+
+@example l2fwd-crypto/main.c
+
+@example l2fwd-ivshmem/guest/guest.c
+
+@example l2fwd-ivshmem/host/host.c
+
+@example l2fwd-jobstats/main.c
+
+@example l2fwd-keepalive/main.c
+
+@example l2fwd/main.c
+
+@example l3fwd-acl/main.c
+
+@example l3fwd/main.c
+
+@example l3fwd-power/main.c
+
+@example l3fwd-vf/main.c
+
+@example link_status_interrupt/main.c
+
+@example load_balancer/config.c
+
+@example load_balancer/init.c
+
+@example load_balancer/main.c
+
+@example load_balancer/runtime.c
+
+@example multi_process/client_server_mp/mp_client/client.c
+
+@example multi_process/client_server_mp/mp_server/args.c
+
+@example multi_process/client_server_mp/mp_server/init.c
+
+@example multi_process/client_server_mp/mp_server/main.c
+
+@example multi_process/l2fwd_fork/flib.c
+
+@example multi_process/l2fwd_fork/main.c
+
+@example multi_process/simple_mp/main.c
+
+@example multi_process/simple_mp/mp_commands.c
+
+@example multi_process/symmetric_mp/main.c
+
+@example netmap_compat/bridge/bridge.c
+
+@example netmap_compat/lib/compat_netmap.c
+
+@example packet_ordering/main.c
+
+@example performance-thread/common/arch/x86/ctx.c
+
+@example performance-thread/common/lthread.c
+
+@example performance-thread/common/lthread_cond.c
+
+@example performance-thread/common/lthread_diag.c
+
+@example performance-thread/common/lthread_mutex.c
+
+@example performance-thread/common/lthread_sched.c
+
+@example performance-thread/common/lthread_tls.c
+
+@example performance-thread/l3fwd-thread/main.c
+
+@example performance-thread/pthread_shim/main.c
+
+@example performance-thread/pthread_shim/pthread_shim.c
+
+@example ptpclient/ptpclient.c
+
+@example qos_meter/main.c
+
+@example qos_meter/rte_policer.c
+
+@example qos_sched/app_thread.c
+
+@example qos_sched/args.c
+
+@example qos_sched/cfg_file.c
+
+@example qos_sched/cmdline.c
+
+@example qos_sched/init.c
+
+@example qos_sched/main.c
+
+@example qos_sched/stats.c
+
+@example quota_watermark/qw/args.c
+
+@example quota_watermark/qwctl/commands.c
+
+@example quota_watermark/qwctl/qwctl.c
+
+@example quota_watermark/qw/init.c
+
+@example quota_watermark/qw/main.c
+
+@example rxtx_callbacks/main.c
+
+@example skeleton/basicfwd.c
+
+@example tep_termination/main.c
+
+@example tep_termination/vxlan.c
+
+@example tep_termination/vxlan_setup.c
+
+@example timer/main.c
+
+@example vhost/main.c
+
+@example vhost_xen/main.c
+
+@example vhost_xen/vhost_monitor.c
+
+@example vhost_xen/xenstore_parse.c
+
+@example vmdq_dcb/main.c
+
+@example vmdq/main.c
+
+@example vm_power_manager/channel_manager.c
+
+@example vm_power_manager/channel_monitor.c
+
+@example vm_power_manager/guest_cli/main.c
+
+@example vm_power_manager/guest_cli/vm_power_cli_guest.c
+
+@example vm_power_manager/main.c
+
+@example vm_power_manager/power_manager.c
+
+@example vm_power_manager/vm_power_cli.c
+
+*/
-- 
2.5.0

Re: [dpdk-dev] [PATCH] doc: add example programs to doxygen api docs

[Thomas Monjalon]

2015-12-11 13:41, John McNamara:
> Enable Doxygen parsing of DPDK example files so that the example
> code is linked to and from the API docs. This allows the reader
> to see examples of API usage in context by following a link.
> 
> Signed-off-by: John McNamara <john.mcnamara@intel.com>

Note sure of the benefit.
I think it would make more sense if an example was linked from the
related API, e.g. l3fwd-acl from rte_acl.h.

Re: [dpdk-dev] [PATCH] doc: add example programs to doxygen api docs

[Mcnamara, John]

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Friday, December 11, 2015 1:45 PM
> To: Mcnamara, John
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH] doc: add example programs to doxygen api
> docs
> 
> 2015-12-11 13:41, John McNamara:
> > Enable Doxygen parsing of DPDK example files so that the example code
> > is linked to and from the API docs. This allows the reader to see
> > examples of API usage in context by following a link.
> >
> > Signed-off-by: John McNamara <john.mcnamara@intel.com>
> 
> Note sure of the benefit.
> I think it would make more sense if an example was linked from the related
> API, e.g. l3fwd-acl from rte_acl.h.

Hi,

That is more or less the way it works. The links are bidirectional header/api <-> example.

Have a look at the rte_acl.h html output after the patch is applied.

John.
-- 

Re: [dpdk-dev] [PATCH] doc: add example programs to doxygen api docs

[Thomas Monjalon]

2015-12-11 14:31, Mcnamara, John:
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> > 2015-12-11 13:41, John McNamara:
> > > Enable Doxygen parsing of DPDK example files so that the example code
> > > is linked to and from the API docs. This allows the reader to see
> > > examples of API usage in context by following a link.
> > >
> > > Signed-off-by: John McNamara <john.mcnamara@intel.com>
> > 
> > Note sure of the benefit.
> > I think it would make more sense if an example was linked from the related
> > API, e.g. l3fwd-acl from rte_acl.h.
> 
> Hi,
> 
> That is more or less the way it works. The links are bidirectional header/api <-> example.
> 
> Have a look at the rte_acl.h html output after the patch is applied.

Yes, it's nice.
Applied with minor changes, thanks