From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 8EFB5A0C4F; Fri, 23 Jul 2021 02:03:18 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 234CC40040; Fri, 23 Jul 2021 02:03:18 +0200 (CEST) Received: from mail-qk1-f174.google.com (mail-qk1-f174.google.com [209.85.222.174]) by mails.dpdk.org (Postfix) with ESMTP id C4B104003C for ; Fri, 23 Jul 2021 02:03:16 +0200 (CEST) Received: by mail-qk1-f174.google.com with SMTP id bm6so7196948qkb.1 for ; Thu, 22 Jul 2021 17:03:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=broadcom.com; s=google; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=geH26gbM8OGmjEXZIGIO5lsTc7m0MYcP/p77hAQVGmY=; b=bpv6HU5Th/KdXR9qbGUxyhrl8GCerZ0ZlkdbdcYeFep0KnqfNt0x6aEbvNuqIpZP+g 5yP5aFWb3E1KixgoMtNF8jCL6QXH/2CzRszjbJ0CKlvawR5b3bcGRADePbRPkhQ8Ah+v EVWIUSuNgNK0BYJ6CZOrfUBxVDWvEVRpdoZSk= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=geH26gbM8OGmjEXZIGIO5lsTc7m0MYcP/p77hAQVGmY=; b=Sl8o3zwLWaNdzalo8U3u2xSfpE6ZBoETIHG3d2h2OzYrH6tF5wuL+lsV22hhuyy7rZ QX5Y1Zxpj0nIvxk8+fPWgptqzrNFb27cvqaXpWb2q1/JZn9G+YTI6A57SFxg6TuA0VTo ae/eu2MT1LmAs1fZ12B1ZNNcEydwSGikj5lM3/64pVcc5YxXoigASvsxk7OmZhqu6Pk+ AuVcrB85HrtCK/HNUAYpgBVYMkYLETBH29mGLGGa5zc2MURQKcxNLZALfVhl17THpPf2 K/vYOSGWByz5UUCPteoVHgRkCsN0P7rCdW0G21csCmOw+5gsw7sBCc7XiTpvDKGXAG/T S6tQ== X-Gm-Message-State: AOAM5338l9x4AgSGjmfASHy+fzL8TPqb1sDPIYLKmnZ0JcOBdbjz19cl EsqZiobdZVsHp1v67SF/iMBkzpHoOU7ISl/1L1ml1g== X-Google-Smtp-Source: ABdhPJxgm8oz4se2zfz9kpQdpR8L3+ECe9FkpU44zsvqSGfU7Y6IpNsvh8xRvDxjpwOHIToSLX23YYabFg/TsRvbHXc= X-Received: by 2002:a05:620a:120b:: with SMTP id u11mr2219655qkj.455.1626998596020; Thu, 22 Jul 2021 17:03:16 -0700 (PDT) MIME-Version: 1.0 References: <2236865.drsZmlonQt@thomas> In-Reply-To: <2236865.drsZmlonQt@thomas> From: Ajit Khaparde Date: Thu, 22 Jul 2021 17:02:59 -0700 Message-ID: To: Thomas Monjalon Cc: Asaf Penso , "users@dpdk.org" , dpdk-dev , David Marchand , Bruce Richardson , Ferruh Yigit , Jerin Jacob Kollanukkaran , Akhil Goyal , Maxime Coquelin Content-Type: multipart/signed; protocol="application/pkcs7-signature"; micalg=sha-256; boundary="00000000000063351905c7bf215c" X-Content-Filtered-By: Mailman/MimeDel 2.1.29 Subject: Re: [dpdk-dev] [dpdk-users] [DISCUSSION] code snippet documentation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" --00000000000063351905c7bf215c Content-Type: text/plain; charset="UTF-8" On Thu, Jul 22, 2021 at 1:29 PM Thomas Monjalon 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? > > --00000000000063351905c7bf215c--