Message ID | 20181018160858.23114-1-thomas@monjalon.net (mailing list archive) |
---|---|
State | Rejected, archived |
Delegated to: | Thomas Monjalon |
Headers |
Return-Path: <dev-bounces@dpdk.org> X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 90BF61B142; Thu, 18 Oct 2018 18:09:06 +0200 (CEST) Received: from out3-smtp.messagingengine.com (out3-smtp.messagingengine.com [66.111.4.27]) by dpdk.org (Postfix) with ESMTP id 7B6371B12A for <dev@dpdk.org>; Thu, 18 Oct 2018 18:09:05 +0200 (CEST) Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailout.nyi.internal (Postfix) with ESMTP id 1358C229C3; Thu, 18 Oct 2018 12:09:05 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute1.internal (MEProxy); Thu, 18 Oct 2018 12:09:05 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; s=mesmtp; bh=t11BCTJC2Mjyc/phWFlmydv VsfFYyRh7qvmhl6xC2pA=; b=jcVhWfYKd2rMD6UtGXDc1mGX97TYxtVAX+62Ft+ VjB+0Eng4Xzlr1eyGw763aGm028u6ZyzCAessXHrPMU2uQAYTZbo7ZAX50jRNmb4 xzlD/T5Nya7zL9oKud+t4wNgcIwoKuDamuQWjF2iUVJ4D2QE2/nVWijzGFFqC8VW 3FFA= DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:date:from :message-id:mime-version:subject:to:x-me-proxy:x-me-proxy :x-me-sender:x-me-sender:x-sasl-enc; s=fm1; bh=t11BCTJC2Mjyc/phW FlmydvVsfFYyRh7qvmhl6xC2pA=; b=TZS98DF2lyOr+ahBBZ4oy52iDllnMNUdM Go8NGG8RlRHbWW8FDMUe8yo1WdZLYVW62+w555fgAk8/KGJjso+MlQOosrNHFFEq aRVkOIVbOid1azg4lrNf9QkOAa51ShFTf8lQPVJtEpmlDllYGx8Mm5TPnGmcIcwg h8ODDebdTfDSUs5MSPgYECkRPG8Yu7vUPrzIzy1ceLnZHnzc2TR5aYs+npgzCE/I m4dYFxbIKSNLVFTjRLH+yXCH+LxxKf8I5xg9yX9ubNcbbg2WHd+sylgjHIumutsh XiiP67czCucPAPf47TAzeuQiMd4Vx4L8lN1nf4hylRoBYHt/GFEaw== X-ME-Sender: <xms:ILDIW7FTbIH-fBIf2UjIypDNmyso3KmoyHT8yDuDyiZcFTx17ajDCw> X-ME-Proxy: <xmx:ILDIW-c7lElEEv-KaRjdd7k5eOCj7qcJMNCYfKLnza2NarBL7WzPqA> <xmx:ILDIWyiykJ_A5BnsZ8FWPU5rZ0_uaZuaXouwPA7rpHKtr5SkcZKKtA> <xmx:ILDIW3C7HiBafAUxPVxbDT5M8PJJHZhILtj_ZhocB1S-fG0Fp03ndg> <xmx:ILDIW6ujbAhJf9DeCZOQqgfDJA3ECW2_nFPp9A-LouFG5TMMAILuLw> <xmx:ILDIW7Kf9PHWTvc2NVQoq9qon1oguFydkq9KlWaRLvbAP4BGb4tteQ> <xmx:IbDIWyn_b4CECXr3BMDvBfQjDstSGa-z3BIDtWD-TR8oJNMrKUdt6g> Received: from xps.monjalon.net (184.203.134.77.rev.sfr.net [77.134.203.184]) by mail.messagingengine.com (Postfix) with ESMTPA id AA084E4408; Thu, 18 Oct 2018 12:09:03 -0400 (EDT) From: Thomas Monjalon <thomas@monjalon.net> To: dev@dpdk.org Cc: john.mcnamara@intel.com, marko.kovacevic@intel.com Date: Thu, 18 Oct 2018 18:08:58 +0200 Message-Id: <20181018160858.23114-1-thomas@monjalon.net> X-Mailer: git-send-email 2.19.0 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH] doc: show internal functions in doxygen X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions <dev.dpdk.org> List-Unsubscribe: <https://mails.dpdk.org/options/dev>, <mailto:dev-request@dpdk.org?subject=unsubscribe> List-Archive: <http://mails.dpdk.org/archives/dev/> List-Post: <mailto:dev@dpdk.org> List-Help: <mailto:dev-request@dpdk.org?subject=help> List-Subscribe: <https://mails.dpdk.org/listinfo/dev>, <mailto:dev-request@dpdk.org?subject=subscribe> Errors-To: dev-bounces@dpdk.org Sender: "dev" <dev-bounces@dpdk.org> |
Series |
doc: show internal functions in doxygen
|
|
Checks
Context | Check | Description |
---|---|---|
ci/Intel-compilation | success | Compilation OK |
ci/checkpatch | success | coding style OK |
Commit Message
Thomas Monjalon
Oct. 18, 2018, 4:08 p.m. UTC
Not sure we want to show the internal functions to users.
It may be useful only for PMD developers.
Do we vote? +1 / -1 welcome!
Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
doc/api/doxy-api.conf.in | 1 +
1 file changed, 1 insertion(+)
Comments
On 10/18/2018 5:08 PM, Thomas Monjalon wrote: > Not sure we want to show the internal functions to users. > It may be useful only for PMD developers. > Do we vote? +1 / -1 welcome! What is affected from this setting, can you give an example what was not shown will be shown now? > > Signed-off-by: Thomas Monjalon <thomas@monjalon.net> > --- > doc/api/doxy-api.conf.in | 1 + > 1 file changed, 1 insertion(+) > > diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in > index 3b652ac9c..85834c9e7 100644 > --- a/doc/api/doxy-api.conf.in > +++ b/doc/api/doxy-api.conf.in > @@ -71,6 +71,7 @@ MACRO_EXPANSION = YES > EXPAND_ONLY_PREDEF = YES > EXTRACT_STATIC = YES > DISTRIBUTE_GROUP_DOC = YES > +INTERNAL_DOCS = YES > HIDE_UNDOC_MEMBERS = YES > HIDE_UNDOC_CLASSES = YES > HIDE_SCOPE_NAMES = YES >
18/10/2018 18:22, Ferruh Yigit: > On 10/18/2018 5:08 PM, Thomas Monjalon wrote: > > Not sure we want to show the internal functions to users. > > It may be useful only for PMD developers. > > Do we vote? +1 / -1 welcome! > > What is affected from this setting, can you give an example what was not shown > will be shown now? For instance, most of the things in rte_ethdev_core.h. All the doxygen with @internal tag are affected.
On 10/18/2018 6:04 PM, Thomas Monjalon wrote: > 18/10/2018 18:22, Ferruh Yigit: >> On 10/18/2018 5:08 PM, Thomas Monjalon wrote: >>> Not sure we want to show the internal functions to users. >>> It may be useful only for PMD developers. >>> Do we vote? +1 / -1 welcome! >> >> What is affected from this setting, can you give an example what was not shown >> will be shown now? > > For instance, most of the things in rte_ethdev_core.h. > All the doxygen with @internal tag are affected. rte_ethdev_core.h is not part of API documentation but I randomly checked rte_lpm.h which has some @internal structures. But those in the lpm header is the ones for ABI versioning, I think it is confusing to expose them to the user, and documentation doesn't highlight that it is internal. So not a strong opinion, but from my side -1
On Friday 19 October 2018 01:09 PM, Ferruh Yigit wrote: > On 10/18/2018 6:04 PM, Thomas Monjalon wrote: >> 18/10/2018 18:22, Ferruh Yigit: >>> On 10/18/2018 5:08 PM, Thomas Monjalon wrote: >>>> Not sure we want to show the internal functions to users. >>>> It may be useful only for PMD developers. >>>> Do we vote? +1 / -1 welcome! >>> >>> What is affected from this setting, can you give an example what was not shown >>> will be shown now? >> >> For instance, most of the things in rte_ethdev_core.h. >> All the doxygen with @internal tag are affected. > > rte_ethdev_core.h is not part of API documentation but I randomly checked > rte_lpm.h which has some @internal structures. > > But those in the lpm header is the ones for ABI versioning, I think it is > confusing to expose them to the user, and documentation doesn't highlight that > it is internal. > > So not a strong opinion, but from my side -1 > -1 from me as well. Even I think it would be overload of information in Doxygen. And to add, some places might require re-documenting to cleanup internal markers. My opinion: direct code would help better than doxygen for these cases.
diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in index 3b652ac9c..85834c9e7 100644 --- a/doc/api/doxy-api.conf.in +++ b/doc/api/doxy-api.conf.in @@ -71,6 +71,7 @@ MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES EXTRACT_STATIC = YES DISTRIBUTE_GROUP_DOC = YES +INTERNAL_DOCS = YES HIDE_UNDOC_MEMBERS = YES HIDE_UNDOC_CLASSES = YES HIDE_SCOPE_NAMES = YES