From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 82980A0C47; Thu, 15 Jul 2021 10:28:58 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 6A67A40686; Thu, 15 Jul 2021 10:28:58 +0200 (CEST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mails.dpdk.org (Postfix) with ESMTP id B9D1F4014D for ; Thu, 15 Jul 2021 10:28:57 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1626337737; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=ZxsA8VuKuO93t7LerQB5ksyLInL4tRIkwjMEiTCrzSQ=; b=cSdIrGSigxWsPyshYCm3M0b0/TxYCUTwTICpz7LmJiaGpBmHycgY92MdNCJda+zaw4RVw+ nkHYYH6rH4aAVV6dqMz5ysjpLDGBSgdaCnBlwaQLpKrs+FmfEJPTqU9iYOgXV/M3bQvvLt 0SIxjyAfV/ZiUiGZaaJtQUAaTB9AOeo= Received: from mail-ua1-f72.google.com (mail-ua1-f72.google.com [209.85.222.72]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-588-vEY8RyokNkqVlh1nzrmq_A-1; Thu, 15 Jul 2021 04:28:56 -0400 X-MC-Unique: vEY8RyokNkqVlh1nzrmq_A-1 Received: by mail-ua1-f72.google.com with SMTP id j5-20020ab06ca50000b02902a1305400e5so1349873uaa.13 for ; Thu, 15 Jul 2021 01:28:56 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=ZxsA8VuKuO93t7LerQB5ksyLInL4tRIkwjMEiTCrzSQ=; b=US21xw08haWTWCXHdskpFe6a9KhLvKWqFw68ESv/SR4KiB89ehPW+AvHy+LhL/Zv0p yb36lV+jVb+Aj6CiHrrOgs+pKpQFLNEpMbrK03IyyQXzmRdpweX//GTKPZ/NEWIRGorJ SSTBJjCJgJg2ULuC+9v3ihuE83ROckzh23mz6Obe6RlFXDpExkyQlL12NLdTYofAkJ29 3sJuMdDSM8nX1SyYqHaR1+g5/3OMwrFIwKyq7HoEScYZgsTrSfgIVY6yBTHM6cClLkfE vrOvvB6ZqQv8k/eAx4Mh78FdYpBfDVFltichCms5uDtR17ZWoaPMSrtluBGVQQtWSX12 YSTA== X-Gm-Message-State: AOAM533dLWjn5HE2w40jEqhEeoSBx4mFFyER/UZIiEwksi6TlUPn23Ae UomsLrmnXkY3httsYHw2fANGXfceVfmQynw8nHCokPkKentXfW8/PfkHY9p9Rbu0hm8NKpKONow l3PFJlcXe5nRCoCmrf5s= X-Received: by 2002:ac5:c888:: with SMTP id n8mr4629262vkl.22.1626337735673; Thu, 15 Jul 2021 01:28:55 -0700 (PDT) X-Google-Smtp-Source: ABdhPJxmzJVUJAamhlBfL1rZ+g5YwV5j/5gHK67q72j7LI5KJrl212WC8zJTSc3k/sUKJMUCpwL8ibQbKVVKrTyzoEU= X-Received: by 2002:ac5:c888:: with SMTP id n8mr4629231vkl.22.1626337735484; Thu, 15 Jul 2021 01:28:55 -0700 (PDT) MIME-Version: 1.0 References: <20210714095827.3248027-1-conor.fogarty@intel.com> In-Reply-To: <20210714095827.3248027-1-conor.fogarty@intel.com> From: David Marchand Date: Thu, 15 Jul 2021 10:28:43 +0200 Message-ID: To: Conor Fogarty Cc: Olivier Matz , "Iremonger, Bernard" , Ori Kam , Bruce Richardson , "Ananyev, Konstantin" , Tomasz Kantecki , Sunil Kumar Kori , Pavan Nikhilesh , Jerin Jacob Kollanukkaran , Kiran Kumar Kokkilagadda , Nithin Dabilpuram , David Hunt , "Burakov, Anatoly" , Cristian Dumitrescu , "Singh, Jasvinder" , "Mcnamara, John" , Byron Marohn , "Wang, Yipeng1" , Van Haaren Harry , Robert Sanford , Erik Gabriel Carrillo , Declan Doherty , Kirill Rybalchenko , Thomas Monjalon , Conor Walsh , dev Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=dmarchan@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" Subject: Re: [dpdk-dev] [PATCH] doc/sample_app_ug: use code snippets in sample app guides X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Hello, On Wed, Jul 14, 2021 at 11:59 AM Conor Fogarty 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 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