From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 988E0A0471 for ; Thu, 18 Jul 2019 17:09:23 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 6822B1B951; Thu, 18 Jul 2019 17:09:23 +0200 (CEST) Received: from wout5-smtp.messagingengine.com (wout5-smtp.messagingengine.com [64.147.123.21]) by dpdk.org (Postfix) with ESMTP id 48F6F1B94F for ; Thu, 18 Jul 2019 17:09:21 +0200 (CEST) Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailout.west.internal (Postfix) with ESMTP id 41ED54C8; Thu, 18 Jul 2019 11:09:20 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute1.internal (MEProxy); Thu, 18 Jul 2019 11:09:20 -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=mesmtp; bh=Rvzthd/Qy1ELxYqVOJs0IKKSmQ52sJ9NPDdKnAV9Zo0=; b=bge3hkCIG8H4 aLrbG8pvgoCR9/s4u0Lg7apn0ECGBuakI3YAHkNhrGLpgwqo/og9ZjemXOrofgsP VxsVdkpWCK2qBKekRcOpZKiDbGIBtB9eMpI6yv7OZxDFaQeQYDwcz2SLIpTgQBC+ jHW6UqFEggZNlpkcO0+Yb66BkCPmEM4= 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=Rvzthd/Qy1ELxYqVOJs0IKKSmQ52sJ9NPDdKnAV9Z o0=; b=vP5J/23irLQReZ9pHBHK1xVF/5xL8Pq9zlcJWMdtpC+vQZ2psshIlbIB1 mHSNAzX926pfJUWgvBkAligSvpay7g5VO+4dWnEtE/P80/XUWvZ4r+p9q+uspoiZ eQ6vpw8fggDJ/NGAHvNHnVES2HmFzahDeQVa/FMnxdYNykLwDMjRXzgkGXDTopLn eziT9CvqTdJ5n/4yMaa0ygeA8WQSUAK3CRg3sDbk/XdPgY3vj9+oYvLSZzEn5pTS JsjNopK80cOullf6fonHTSQEZnZQpVpecZa6QtCScVT8K9k3b7ywqICy9PkABeVF 5NkqzJvsPSN/FSqGfSAAs+lP2Tl8A== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduvddrieehgdekjecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpefhvffufffkjghfggfgtgesthfuredttddtvdenucfhrhhomhepvfhhohhmrghs ucfoohhnjhgrlhhonhcuoehthhhomhgrshesmhhonhhjrghlohhnrdhnvghtqeenucffoh hmrghinhepughpughkrdhorhhgnecukfhppeejjedrudefgedrvddtfedrudekgeenucfr rghrrghmpehmrghilhhfrhhomhepthhhohhmrghssehmohhnjhgrlhhonhdrnhgvthenuc evlhhushhtvghrufhiiigvpedt X-ME-Proxy: Received: from xps.localnet (184.203.134.77.rev.sfr.net [77.134.203.184]) by mail.messagingengine.com (Postfix) with ESMTPA id ED87B80064; Thu, 18 Jul 2019 11:09:18 -0400 (EDT) From: Thomas Monjalon To: "Chautru, Nicolas" Cc: "Mcnamara, John" , "Kovacevic, Marko" , "dev@dpdk.org" Date: Thu, 18 Jul 2019 17:09:17 +0200 Message-ID: <65166887.pMNS0f2l0f@xps> In-Reply-To: <1183128033837D43A851F70F33ED5C575C1FD52C@FMSMSX109.amr.corp.intel.com> References: <20190717220123.6165-1-thomas@monjalon.net> <65166682.iuaK6TOrCN@xps> <1183128033837D43A851F70F33ED5C575C1FD52C@FMSMSX109.amr.corp.intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" Subject: Re: [dpdk-dev] [PATCH] doc: fix PDF build of bbdev prog guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 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" 18/07/2019 16:59, Chautru, Nicolas: > From: Thomas Monjalon [mailto:thomas@monjalon.net] > >18/07/2019 15:33, Chautru, Nicolas: > >> From: Thomas Monjalon [mailto:thomas@monjalon.net] > >> >Anyway all the documentation about the API details should be removed. > >> >The guide is expected to give an understanding of the whole design, not replacing the details maintained in the doxygen comments. > >> > >> Thanks Thomas. > >> These tables are arguably useful on that page with the related contextual verbose information aside which provide more context usage. Still I am reformatting into simpler table structure. > >> I have just pushed a parallel patch here : > >> https://patches.dpdk.org/patch/56715/ > > > >Sorry, I am not sure to understand. > >You want to keep all this information? > > I would rather yes. I can see your point with some redundancy between code and documentation, but the bbdev.rst documentation is arguably clearer as it is : the detailed information in paragraphs puts into context some of the information captured in a nice and concise table. Clearer than having to go back and forth in doxygen capturing some of this in a less compact format (which still has its own complementary value). Matter of opinion, let me know if you have a fundamental concern with keeping such table in that document. I am not sure it is clearer to document all parameters in rst. The main concern is about maintainability. When we change something in the code, we change the doxygen and we forget the rst guide. The other concern is that maybe the doxygen is not complete. My advice is to reference the doxygen when the information is the same.