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 BADF6A0A0C; Thu, 22 Jul 2021 22:29:41 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 4D6914014D; Thu, 22 Jul 2021 22:29:41 +0200 (CEST) Received: from out1-smtp.messagingengine.com (out1-smtp.messagingengine.com [66.111.4.25]) by mails.dpdk.org (Postfix) with ESMTP id 3C86040040; Thu, 22 Jul 2021 22:29:40 +0200 (CEST) Received: from compute4.internal (compute4.nyi.internal [10.202.2.44]) by mailout.nyi.internal (Postfix) with ESMTP id BB07F5C012E; Thu, 22 Jul 2021 16:29:39 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute4.internal (MEProxy); Thu, 22 Jul 2021 16:29:39 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding:content-type; s=fm1; bh= C/8BPlQIUGLLIaBWnAopY01mZsQtPnwKHoZUKJG8nII=; b=G+4IJ0K9J39oaGqI jWffFqezyuBYzruekGs4UWuqrX1CVoh+nr4UrvAPaIMyuRm8NJzUWWkNTixPFemh rCnunm7Yr86u4eaaNXn6wOPJjv8tpBEFJiYoYJriDrxf38/UGVvLXJsArOfIzxhL 8v7Z4QOIAO3aypq5rpFFacgeE1rl1VkGHlgFO8A8loYaGGW8EKOUfTJHmZpMhuyE 6m5YElaZ5E9v++4R5n8MKSAaFYFtOy6nMEhKCEEWUmPYJQ6E0GLQwrECIeQPnDe2 QL6FlxBkKBgxqhXaCd4G4HuIFnoQwYD+SgH1LkrDBGiM9O8T1SY97QNEBz7BT3fv Zna2YA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm3; bh=C/8BPlQIUGLLIaBWnAopY01mZsQtPnwKHoZUKJG8n II=; b=MVEjmc3HVJ7LrOOZRiIYL+646DSeAifgnr7ty6p3nScprd+kQNdILmCUR eADFAz5ebLy364TOavnIqYcac2Icn7mIe1uzxyL8uUbCsfT568MBbDMtK0jq/IV7 JCQQqUc5zp/dPchRWkwfWjWpS85/xRgjZCIZc4XhmFc9C7j/q4zdY1ooUUHi+iR9 fUJiZYpScWKdwLnmruX44IYapfFs+FbVSnOwewOi5g6zrduud16mJP1ZB6QyUZgp X6jhsmEtwsP0RtrY2Ok3sEsek9tEaSPmpI+UH4crDT+oAudOQNKkcBHgGLYNuoha Nzn8maZVJc8CjwuyiqtpxrkNlrz+w== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvtddrfeeigddufeelucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephffvufffkfgjfhgggfgtsehtufertddttddvnecuhfhrohhmpefvhhhomhgr shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg ftrfgrthhtvghrnhepudeggfdvfeduffdtfeeglefghfeukefgfffhueejtdetuedtjeeu ieeivdffgeehnecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrh homhepthhhohhmrghssehmohhnjhgrlhhonhdrnhgvth X-ME-Proxy: Received: by mail.messagingengine.com (Postfix) with ESMTPA; Thu, 22 Jul 2021 16:29:37 -0400 (EDT) From: Thomas Monjalon To: Asaf Penso Cc: "users@dpdk.org" , dev@dpdk.org, david.marchand@redhat.com, bruce.richardson@intel.com, ferruh.yigit@intel.com, ajit.khaparde@broadcom.com, jerinj@marvell.com, gakhil@marvell.com, maxime.coquelin@redhat.com Date: Thu, 22 Jul 2021 22:29:56 +0200 Message-ID: <2236865.drsZmlonQt@thomas> In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" 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" 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?