[dpdk-dev] [PATCH] doc: show internal functions in doxygen

[dpdk-dev] [PATCH] doc: show internal functions in doxygen

[Thomas Monjalon]

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

Re: [dpdk-dev] [PATCH] doc: show internal functions in doxygen

[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?

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

Re: [dpdk-dev] [PATCH] doc: show internal functions in doxygen

[Thomas Monjalon]

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.

Re: [dpdk-dev] [PATCH] doc: show internal functions in doxygen

[Ferruh Yigit]

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

Re: [dpdk-dev] [PATCH] doc: show internal functions in doxygen

[Shreyansh Jain]

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.