DPDK patches and discussions
 help / color / mirror / Atom feed
* [dpdk-dev] [PATCH] doc: show internal functions in doxygen
@ 2018-10-18 16:08 Thomas Monjalon
  2018-10-18 16:22 ` Ferruh Yigit
  0 siblings, 1 reply; 5+ messages in thread
From: Thomas Monjalon @ 2018-10-18 16:08 UTC (permalink / raw)
  To: dev; +Cc: john.mcnamara, marko.kovacevic

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(+)

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
-- 
2.19.0

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: show internal functions in doxygen
  2018-10-18 16:08 [dpdk-dev] [PATCH] doc: show internal functions in doxygen Thomas Monjalon
@ 2018-10-18 16:22 ` Ferruh Yigit
  2018-10-18 17:04   ` Thomas Monjalon
  0 siblings, 1 reply; 5+ messages in thread
From: Ferruh Yigit @ 2018-10-18 16:22 UTC (permalink / raw)
  To: Thomas Monjalon, dev; +Cc: john.mcnamara, marko.kovacevic

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
> 

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: show internal functions in doxygen
  2018-10-18 16:22 ` Ferruh Yigit
@ 2018-10-18 17:04   ` Thomas Monjalon
  2018-10-19  7:39     ` Ferruh Yigit
  0 siblings, 1 reply; 5+ messages in thread
From: Thomas Monjalon @ 2018-10-18 17:04 UTC (permalink / raw)
  To: Ferruh Yigit; +Cc: dev, john.mcnamara, marko.kovacevic

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.

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: show internal functions in doxygen
  2018-10-18 17:04   ` Thomas Monjalon
@ 2018-10-19  7:39     ` Ferruh Yigit
  2018-10-22  6:15       ` Shreyansh Jain
  0 siblings, 1 reply; 5+ messages in thread
From: Ferruh Yigit @ 2018-10-19  7:39 UTC (permalink / raw)
  To: Thomas Monjalon; +Cc: dev, john.mcnamara, marko.kovacevic

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

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: show internal functions in doxygen
  2018-10-19  7:39     ` Ferruh Yigit
@ 2018-10-22  6:15       ` Shreyansh Jain
  0 siblings, 0 replies; 5+ messages in thread
From: Shreyansh Jain @ 2018-10-22  6:15 UTC (permalink / raw)
  To: Ferruh Yigit, Thomas Monjalon; +Cc: dev, john.mcnamara, marko.kovacevic

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.

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2018-10-22  6:15 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-10-18 16:08 [dpdk-dev] [PATCH] doc: show internal functions in doxygen Thomas Monjalon
2018-10-18 16:22 ` Ferruh Yigit
2018-10-18 17:04   ` Thomas Monjalon
2018-10-19  7:39     ` Ferruh Yigit
2018-10-22  6:15       ` Shreyansh Jain

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).