RE: [dpdk-users] [DISCUSSION] code snippet documentation

-----Original Message-----
From: dev <redacted> On Behalf Of Asaf Penso
Sent: Sunday, July 25, 2021 7:54 AM
To: Ferruh Yigit <redacted>; Ajit Khaparde
[off-list ref]; NBU-Contact-Thomas Monjalon
[off-list ref]
Cc: users@dpdk.org; dpdk-dev <redacted>; David Marchand
[off-list ref]; Bruce Richardson
[off-list ref]; Jerin Jacob Kollanukkaran
[off-list ref]; Akhil Goyal [off-list ref]; Maxime Coquelin
[off-list ref]; Honnappa Nagarahalli
[off-list ref]; Tu, Lijuan [off-list ref]
Subject: Re: [dpdk-dev] [dpdk-users] [DISCUSSION] code snippet
documentation

Regards,
Asaf Penso

quoted

-----Original Message-----
From: Ferruh Yigit <redacted>
Sent: Friday, July 23, 2021 3:04 PM
To: Ajit Khaparde <ajit.khaparde@broadcom.com>; NBU-Contact-Thomas
Monjalon [off-list ref]
Cc: Asaf Penso <redacted>; users@dpdk.org; dpdk-dev
[off-list ref]; David Marchand [off-list ref]; Bruce
Richardson [off-list ref]; Jerin Jacob Kollanukkaran
[off-list ref]; Akhil Goyal [off-list ref]; Maxime Coquelin
[off-list ref]; Honnappa Nagarahalli
[off-list ref]; Tu, Lijuan [off-list ref]
Subject: Re: [dpdk-users] [DISCUSSION] code snippet documentation

On 7/23/2021 1:02 AM, Ajit Khaparde wrote:

quoted

On Thu, Jul 22, 2021 at 1:29 PM Thomas Monjalon

[off-list ref]

quoted

wrote:

quoted

quoted

15/07/2021 09:01, Asaf Penso:

quoted

Hello DPDK community,

I would like to bring up a discussion about a way to have code
snippets as an

example for proper usage.

quoted

quoted

quoted

The DPDK tree is filled with great pieces of code that are well
documented

and maintained in high quality.

quoted

quoted

quoted

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.

quoted

quoted

quoted

This, however, provides means to test but doesn't provide a good
usage

example.

quoted

quoted

quoted

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.

quoted

quoted

quoted

This, however, doesn't provide a good option when we talk about
small

features.

quoted

quoted

quoted

If, for example, we extend rte_flow with an extra action then
providing a full-

blown example application is somewhat an entry barrier.

quoted

quoted

quoted

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.

quoted

quoted

quoted

I'd like to propose another approach that will address the main two

issues:

quoted

remove the entry barrier and assure compilation.

quoted

quoted

quoted

In this approach, inside the "examples" folder we'll create another
folder for

"snippets".

quoted

quoted

quoted

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.

quoted

quoted

quoted

The purpose is not to generate traffic nor read rx/tx packets from
the DPDK

ports.

quoted

quoted

quoted

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:

quoted

quoted

quoted

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.

Thank you Ferruh, Ajit, and Thomas for your replies.
I think the more snippets the merrier and we can categorize them for better
visibility inside the file and among different files.
Limiting would miss the point of having valid code examples for a variety of
cases.
For complex code snippets I fully think that a dedicated test/example app
should be written but my intention of the snippets is something simpler.
Reading only documentation is not practical enough and reviewing an
example app requires too much effort. Snippet is a great tool in between.
Written DTS test can be an option but I think it is too much overhead if one
just wants to show how to use a function or an object, without putting effort
for the "administrative" topics around the snippet.

quoted

quoted

quoted

Please could you provide a more complex example?

A good example for a snippet would be the usage of the Flex Item.
On the one hand, it's complex enough, but on the other hand, I don't see an added value of writing all the code for packet acquisition, packet handle, verification etc.
WDYT?