On Thu, Jul 22, 2021 at 1:29 PM Thomas Monjalon <tho...@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.
>
>
> Please could you provide a more complex example?
>
>
