On 7/23/2021 1:02 AM, Ajit Khaparde wrote:
> 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.
>
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?
>>
>>
