Hello,
On Wed, Jul 14, 2021 at 11:59 AM Conor Fogarty <conor.foga...@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.foga...@intel.com>
Thanks for working on this cleanup.
- I see the CI reported failure on doc generation, please have a look.
- 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.
- Did you check this patch generate the same doc outputs?
> ---
> 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
