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?