[dpdk-dev] [dpdk-users] [DISCUSSION] code snippet documentation

[Thomas Monjalon]

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.

Please could you provide a more complex example?