Re: [dpdk-dev] [PATCH] doc/sample_app_ug: use code snippets in sample app guides

["Walsh, Conor" <conor.walsh@intel.com>]

> Hello,

Hi David, thanks for your reply I will be handling this as Conor Fogarty is OOO.

> 
> On Wed, Jul 14, 2021 at 11:59 AM Conor Fogarty <conor.fogarty@intel.com>
> wrote:
> >
> > Currently the sample app user guides use hard coded code snippets,
> > this patch changes these to use literalinclude which will dynamically
> > update the snippets as changes are made to the code.
> > This was introduced in commit 413c75c33c40 ("doc: show how to include
> > code in guides"). Comments within the sample apps were updated to
> > accommodate this as part of this patch. This will help to ensure that
> > the code within the sample app user guides is up to date and not out
> > of sync with the actual code.
> >
> > Signed-off-by: Conor Fogarty <conor.fogarty@intel.com>
> 
> Thanks for working on this cleanup.
> 
> - I see the CI reported failure on doc generation, please have a look.

This will be fixed in v2

> 
> 
> - I just had a quick look at the patch, and noticed some added
> "cutting" comments have been merged with existing ones, even if
> unrelated.
> Like:
> 
> + /* Pattern 8< */
>  existing code we want to extract
> - /* Some comments unrelated to above block */
> + /* >8 End of Pattern
> +  * Some comments unrelated to above block
> +  */
> 
> This will just generate code churn when such unrelated blocks (and
> their comments) are touched.
> I would simply add /* >8 End of Pattern */ and leave existing comments
> untouched.

I will change this in v2, unrelated comments and doc tags will not be entangled.

> 
> 
> - Did you check this patch generate the same doc outputs?

The output seems to be the same, some code snippets that no longer exist in the code base have been removed,
So that should be the only difference observable from the doc output.

V2 coming soon!

Thanks,
Conor.

> 
> 
> > ---
> >  doc/guides/contributing/documentation.rst     |   4 +-
> >  doc/guides/sample_app_ug/cmd_line.rst         |  64 +--
> >  doc/guides/sample_app_ug/flow_classify.rst    | 435 +++--------------
> >  doc/guides/sample_app_ug/flow_filtering.rst   | 441 ++++-------------
> >  doc/guides/sample_app_ug/hello_world.rst      |  53 +-
> >  doc/guides/sample_app_ug/ioat.rst             | 415 ++++------------
> >  doc/guides/sample_app_ug/ip_frag.rst          |  32 +-
> >  doc/guides/sample_app_ug/ip_reassembly.rst    |  67 +--
> >  doc/guides/sample_app_ug/ipv4_multicast.rst   | 194 ++------
> >  doc/guides/sample_app_ug/keep_alive.rst       |  38 +-
> >  doc/guides/sample_app_ug/l2_forward_cat.rst   |  20 +-
> >  .../sample_app_ug/l2_forward_crypto.rst       | 214 ++-------
> >  doc/guides/sample_app_ug/l2_forward_event.rst | 453 ++++--------------
> >  .../sample_app_ug/l2_forward_job_stats.rst    | 350 +++-----------
> >  .../sample_app_ug/l2_forward_real_virtual.rst | 260 ++--------
> >  doc/guides/sample_app_ug/l3_forward.rst       |  89 +---
> >  doc/guides/sample_app_ug/l3_forward_graph.rst | 167 +------
> >  .../sample_app_ug/l3_forward_power_man.rst    | 159 +-----
> >  doc/guides/sample_app_ug/link_status_intr.rst | 267 +++--------
> >  doc/guides/sample_app_ug/multi_process.rst    |  31 +-
> >  doc/guides/sample_app_ug/ptpclient.rst        | 116 ++---
> >  doc/guides/sample_app_ug/qos_metering.rst     |  42 +-
> >  doc/guides/sample_app_ug/qos_scheduler.rst    | 143 +-----
> >  doc/guides/sample_app_ug/rxtx_callbacks.rst   | 108 +----
> >  doc/guides/sample_app_ug/server_node_efd.rst  | 306 ++----------
> >  doc/guides/sample_app_ug/service_cores.rst    |  52 +-
> >  doc/guides/sample_app_ug/skeleton.rst         | 210 ++------
> >  doc/guides/sample_app_ug/timer.rst            | 133 ++---
> >  .../sample_app_ug/vmdq_dcb_forwarding.rst     | 144 +-----
> >  doc/guides/sample_app_ug/vmdq_forwarding.rst  | 113 +----
> >  examples/cmdline/commands.c                   |   5 +-
> >  examples/cmdline/main.c                       |   4 +
> >  examples/flow_classify/flow_classify.c        |  60 ++-
> >  examples/flow_filtering/flow_blocks.c         |  33 +-
> >  examples/flow_filtering/main.c                |  35 +-
> >  examples/helloworld/main.c                    |   9 +-
> >  examples/ioat/ioatfwd.c                       |  57 ++-
> >  examples/ip_fragmentation/main.c              |   7 +-
> >  examples/ip_reassembly/main.c                 |  13 +-
> >  examples/ipv4_multicast/main.c                |  43 +-
> >  examples/l2fwd-cat/l2fwd-cat.c                |   8 +-
> >  examples/l2fwd-crypto/main.c                  |  30 +-
> >  examples/l2fwd-event/l2fwd_common.c           |  10 +-
> >  examples/l2fwd-event/l2fwd_event.c            |  11 +-
> >  examples/l2fwd-event/l2fwd_event_generic.c    |  11 +-
> >  .../l2fwd-event/l2fwd_event_internal_port.c   |   3 +-
> >  examples/l2fwd-event/l2fwd_poll.c             |  11 +-
> >  examples/l2fwd-event/main.c                   |  14 +-
> >  examples/l2fwd-jobstats/main.c                |  60 ++-
> >  examples/l2fwd-keepalive/main.c               |   7 +-
> >  examples/l2fwd/main.c                         |  36 +-
> >  examples/l3fwd-graph/main.c                   |  11 +-
> >  examples/l3fwd-power/main.c                   |   8 +-
> >  examples/l3fwd/l3fwd_em.c                     |  10 +-
> >  examples/l3fwd/l3fwd_fib.c                    |   6 +-
> >  examples/l3fwd/l3fwd_lpm.c                    |   2 +
> >  examples/link_status_interrupt/main.c         |  48 +-
> >  examples/multi_process/simple_mp/main.c       |   2 +
> >  examples/multi_process/symmetric_mp/main.c    |   4 +-
> >  examples/ptpclient/ptpclient.c                |  28 +-
> >  examples/qos_meter/main.c                     |  10 +-
> >  examples/qos_meter/main.h                     |   4 +-
> >  examples/rxtx_callbacks/main.c                |  12 +-
> >  examples/server_node_efd/node/node.c          |  10 +-
> >  examples/server_node_efd/server/init.c        |   5 +-
> >  examples/server_node_efd/server/main.c        |  14 +-
> >  examples/service_cores/main.c                 |   2 +
> >  examples/skeleton/basicfwd.c                  |  30 +-
> >  examples/timer/main.c                         |  23 +-
> >  examples/vmdq/main.c                          |  16 +-
> >  examples/vmdq_dcb/main.c                      |  10 +-
> >  71 files changed, 1482 insertions(+), 4360 deletions(-)
> 
> Nice diffstat.
> 
> 
> [snip]
> 
> > diff --git a/doc/guides/sample_app_ug/flow_classify.rst
> b/doc/guides/sample_app_ug/flow_classify.rst
> > index 01915971ae..812aaa87b0 100644
> > --- a/doc/guides/sample_app_ug/flow_classify.rst
> > +++ b/doc/guides/sample_app_ug/flow_classify.rst
> > @@ -64,81 +64,12 @@ ACL field definitions for the IPv4 5 tuple rule
> >  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> >  The following field definitions are used when creating the ACL table during
> > -initialisation of the ``Flow Classify`` application..
> > +initialisation of the ``Flow Classify`` application
> 
> It seems unrelated.
> At least leave one final '.'.
> 
> 
> >
> > -.. code-block:: c
> > -
> > -     enum {
> > -         PROTO_FIELD_IPV4,
> > -         SRC_FIELD_IPV4,
> 
> [snip]
> 
> >
> > --------------------------------------------------------------
> > Intel Research and Development Ireland Limited
> > Registered in Ireland
> > Registered Office: Collinstown Industrial Park, Leixlip, County Kildare
> > Registered Number: 308263
> >
> >
> > This e-mail and any attachments may contain confidential material for the
> sole
> > use of the intended recipient(s). Any review or distribution by others is
> > strictly prohibited. If you are not the intended recipient, please contact the
> > sender and delete all copies.
> 
> Please get this trailer removed.
> 
> 
> --
> David Marchand