DPDK patches and discussions
 help / color / mirror / Atom feed
From: Ferruh Yigit <ferruh.yigit@intel.com>
To: Ajit Khaparde <ajit.khaparde@broadcom.com>,
	Thomas Monjalon <thomas@monjalon.net>
Cc: Asaf Penso <asafp@nvidia.com>, "users@dpdk.org" <users@dpdk.org>,
	dpdk-dev <dev@dpdk.org>,
	David Marchand <david.marchand@redhat.com>,
	Bruce Richardson <bruce.richardson@intel.com>,
	Jerin Jacob Kollanukkaran <jerinj@marvell.com>,
	 Akhil Goyal <gakhil@marvell.com>,
	Maxime Coquelin <maxime.coquelin@redhat.com>,
	Honnappa Nagarahalli <Honnappa.Nagarahalli@arm.com>,
	"Tu, Lijuan" <lijuan.tu@intel.com>
Subject: Re: [dpdk-dev] [dpdk-users] [DISCUSSION] code snippet documentation
Date: Fri, 23 Jul 2021 13:03:57 +0100	[thread overview]
Message-ID: <d340a4b8-7999-8c43-1508-0154241a223f@intel.com> (raw)
In-Reply-To: <CACZ4nhtOEm2UqFVMEqUYgSjRj2wW7++p62taqF1752PYz2o4HQ@mail.gmail.com>

On 7/23/2021 1:02 AM, Ajit Khaparde wrote:
> On Thu, Jul 22, 2021 at 1:29 PM Thomas Monjalon <thomas@monjalon.net> wrote:
>>
>> 15/07/2021 09:01, Asaf Penso:
>>> Hello DPDK community,
>>>
>>> I would like to bring up a discussion about a way to have code snippets as an example for proper usage.
>>> The DPDK tree is filled with great pieces of code that are well documented and maintained in high quality.
>>> I feel we are a bit behind when we talk about usage examples.
>>>
>>> One way, whenever we implement a new feature, is to extend one of the test-* under the "app" folder.
>>> This, however, provides means to test but doesn't provide a good usage example.
>>>
>>> Another way is to check the content of the "example" folder and whenever we have a BIG new feature it seems like a good place.
>>> This, however, doesn't provide a good option when we talk about small features.
>>> If, for example, we extend rte_flow with an extra action then providing a full-blown example application is somewhat an entry barrier.
>>>
>>> A third option could be to document it in one of the .rst files we have.
>>> Obviously, this requires high maintenance and no option to assure it still compiles.
>>>
>>> I'd like to propose another approach that will address the main two issues: remove the entry barrier and assure compilation.
>>> In this approach, inside the "examples" folder we'll create another folder for "snippets".
>>> Inside "snippets" we'll have several files per category, for example, rte_flow_snippets.c
>>> Each .c file will include a main function that calls the different use cases we want to give as an example.
>>> The purpose is not to generate traffic nor read rx/tx packets from the DPDK ports.
>>> The purpose is to have a good example that compiles properly.
>>>
>>> Taking the rte_flow_snippets.c as an example its main function would look like this:
>>>
>>> int
>>> main(int argc, char **argv)
>>> {
>>>       rte_flow_snippet_match_5tuple_and_drop();
>>>       rte_flow_snippet_match_geneve_ope_and_rss();
>>>       ...
>>>       Return 0;
>>> }
>>
>> I think we need to have a policy or justification about which snippet
>> is worth to have.
>> My thought is to avoid creating snippets which have no other value
>> than showing a function call.
>> I think there is a value if the context is not simple.
> 
> I agree. Otherwise it will be cluttered with snippets.
> 

I sometimes use DTS code as sample for an API, that has limited context (which I
believe sometimes needed to understand API properly) and of course compiles fine.

What about making mandatory to add a test to DTS for each API/feature, that
ensures a reasonable sample for the API call.

And if the intent is just to provide sample for API call without context, I
believe test-* can help on that, it clarifies good & bad input for an API.

>>
>>
>> Please could you provide a more complex example?
>>
>>


  reply	other threads:[~2021-07-23 12:04 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <DM8PR12MB5494C65A49F85CBD33BE8E34CD129@DM8PR12MB5494.namprd12.prod.outlook.com>
2021-07-21 22:31 ` [dpdk-dev] " Asaf Penso
2021-07-22 20:29 ` [dpdk-dev] [dpdk-users] " Thomas Monjalon
2021-07-23  0:02   ` Ajit Khaparde
2021-07-23 12:03     ` Ferruh Yigit [this message]
2021-07-25  4:53       ` Asaf Penso
2021-11-21 15:11         ` Asaf Penso

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=d340a4b8-7999-8c43-1508-0154241a223f@intel.com \
    --to=ferruh.yigit@intel.com \
    --cc=Honnappa.Nagarahalli@arm.com \
    --cc=ajit.khaparde@broadcom.com \
    --cc=asafp@nvidia.com \
    --cc=bruce.richardson@intel.com \
    --cc=david.marchand@redhat.com \
    --cc=dev@dpdk.org \
    --cc=gakhil@marvell.com \
    --cc=jerinj@marvell.com \
    --cc=lijuan.tu@intel.com \
    --cc=maxime.coquelin@redhat.com \
    --cc=thomas@monjalon.net \
    --cc=users@dpdk.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).