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

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 [off-list ref]
wrote:

quoted

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 <redacted>

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.

quoted

---
 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]

quoted

diff --git a/doc/guides/sample_app_ug/flow_classify.rst

b/doc/guides/sample_app_ug/flow_classify.rst

quoted

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 '.'.

quoted

-.. code-block:: c
-
-     enum {
-         PROTO_FIELD_IPV4,
-         SRC_FIELD_IPV4,

[snip]

quoted

--------------------------------------------------------------
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

quoted

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