typedef output question/issue?

typedef output question/issue?

[Randy Dunlap]

Hi,

If I print a typedef in html (make htmldocs) from a .rst file,
I see:

type dma_cookie_t
    an opaque DMA cookie

Description

if dma_cookie_t is >0 it’s a DMA request cookie, <0 it’s an error code

~~~~~~~~~~~~~~~~~~~

If I print the same typedef in man format, it says 'typedef' instead of
'type', which is what I expect to see.

man formatted output:

Kernel API(9)                     API Manual                     Kernel API(9)

NAME
       typedef dma_cookie_t - an opaque DMA cookie

Description
       if dma_cookie_t is >0 it's a DMA request cookie, <0 it's an error code

November 2024                    dma_cookie_t                    Kernel API(9)



I am using python311-Sphinx 8.0.2-1.2-noarch from openSUSE.

[internet search ...]

The $internet says that one option is to install and use:
Add 'sphinx_autodoc_typehints' to the extensions list in your conf.py file.
I tried that but now I get:
Extension error:
Unknown event name: autodoc-process-signature

Another option is to try a different theme so I reverted to
sphinx_rtd_theme but that didn't help either.

Does anyone know a good solution to this?

thanks.
-- 
~Randy

Re: typedef output question/issue?

[Jani Nikula]

On Wed, 20 Nov 2024, Randy Dunlap <rdunlap@infradead.org> wrote:
> Hi,
>
> If I print a typedef in html (make htmldocs) from a .rst file,
> I see:
>
> type dma_cookie_t
>     an opaque DMA cookie
>
> Description
>
> if dma_cookie_t is >0 it’s a DMA request cookie, <0 it’s an error code
>
> ~~~~~~~~~~~~~~~~~~~
>
> If I print the same typedef in man format, it says 'typedef' instead of
> 'type', which is what I expect to see.

I'm sorry, it's unambigous to me which one you expect.

> man formatted output:
>
> Kernel API(9)                     API Manual                     Kernel API(9)
>
> NAME
>        typedef dma_cookie_t - an opaque DMA cookie
>
> Description
>        if dma_cookie_t is >0 it's a DMA request cookie, <0 it's an error code
>
> November 2024                    dma_cookie_t                    Kernel API(9)

How do you generate the man pages?

> I am using python311-Sphinx 8.0.2-1.2-noarch from openSUSE.
>
> [internet search ...]
>
> The $internet says that one option is to install and use:
> Add 'sphinx_autodoc_typehints' to the extensions list in your conf.py file.
> I tried that but now I get:
> Extension error:
> Unknown event name: autodoc-process-signature

The kernel-doc thing is not hooked up in the Sphinx autodoc processing,
which is more geared towards Python. I presume sphinx_autodoc_typehints
uses autodoc-process-signature which isn't there because the autodoc
Sphinx extension isn't loaded, and even if it were, would not be called
on kernel-doc handling.


BR,
Jani.


>
> Another option is to try a different theme so I reverted to
> sphinx_rtd_theme but that didn't help either.
>
> Does anyone know a good solution to this?
>
> thanks.

-- 
Jani Nikula, Intel

Re: typedef output question/issue?

[Jani Nikula]

On Thu, 21 Nov 2024, Jani Nikula <jani.nikula@linux.intel.com> wrote:
> On Wed, 20 Nov 2024, Randy Dunlap <rdunlap@infradead.org> wrote:
>> Hi,
>>
>> If I print a typedef in html (make htmldocs) from a .rst file,
>> I see:
>>
>> type dma_cookie_t
>>     an opaque DMA cookie
>>
>> Description
>>
>> if dma_cookie_t is >0 it’s a DMA request cookie, <0 it’s an error code
>>
>> ~~~~~~~~~~~~~~~~~~~
>>
>> If I print the same typedef in man format, it says 'typedef' instead of
>> 'type', which is what I expect to see.
>
> I'm sorry, it's unambigous to me which one you expect.

*ambiguous, obvs!

>
>> man formatted output:
>>
>> Kernel API(9)                     API Manual                     Kernel API(9)
>>
>> NAME
>>        typedef dma_cookie_t - an opaque DMA cookie
>>
>> Description
>>        if dma_cookie_t is >0 it's a DMA request cookie, <0 it's an error code
>>
>> November 2024                    dma_cookie_t                    Kernel API(9)
>
> How do you generate the man pages?
>
>> I am using python311-Sphinx 8.0.2-1.2-noarch from openSUSE.
>>
>> [internet search ...]
>>
>> The $internet says that one option is to install and use:
>> Add 'sphinx_autodoc_typehints' to the extensions list in your conf.py file.
>> I tried that but now I get:
>> Extension error:
>> Unknown event name: autodoc-process-signature
>
> The kernel-doc thing is not hooked up in the Sphinx autodoc processing,
> which is more geared towards Python. I presume sphinx_autodoc_typehints
> uses autodoc-process-signature which isn't there because the autodoc
> Sphinx extension isn't loaded, and even if it were, would not be called
> on kernel-doc handling.
>
>
> BR,
> Jani.
>
>
>>
>> Another option is to try a different theme so I reverted to
>> sphinx_rtd_theme but that didn't help either.
>>
>> Does anyone know a good solution to this?
>>
>> thanks.

-- 
Jani Nikula, Intel

Re: typedef output question/issue?

[Randy Dunlap]

On 11/21/24 3:19 AM, Jani Nikula wrote:
> On Thu, 21 Nov 2024, Jani Nikula <jani.nikula@linux.intel.com> wrote:
>> On Wed, 20 Nov 2024, Randy Dunlap <rdunlap@infradead.org> wrote:
>>> Hi,
>>>
>>> If I print a typedef in html (make htmldocs) from a .rst file,
>>> I see:
>>>
>>> type dma_cookie_t
>>>     an opaque DMA cookie
>>>
>>> Description
>>>
>>> if dma_cookie_t is >0 it’s a DMA request cookie, <0 it’s an error code
>>>
>>> ~~~~~~~~~~~~~~~~~~~
>>>
>>> If I print the same typedef in man format, it says 'typedef' instead of
>>> 'type', which is what I expect to see.
>>
>> I'm sorry, it's unambigous to me which one you expect.
> 
> *ambiguous, obvs!

Sorry about that. I would like to see 'typedef' instead of 'type'.

Thanks.

> 
>>
>>> man formatted output:
>>>
>>> Kernel API(9)                     API Manual                     Kernel API(9)
>>>
>>> NAME
>>>        typedef dma_cookie_t - an opaque DMA cookie
>>>
>>> Description
>>>        if dma_cookie_t is >0 it's a DMA request cookie, <0 it's an error code
>>>
>>> November 2024                    dma_cookie_t                    Kernel API(9)
>>
>> How do you generate the man pages?

One function or identifier (struct, union, enum, or typedef) at a time.
Just for testing.

$ scripts/kernel-doc -man -function function_or_identifier file | nroff -man | less

e.g.:
$ scripts/kernel-doc  -man -function dma_cookie_t  include/linux/dmaengine.h  | nroff -man  | less

>>
>>> I am using python311-Sphinx 8.0.2-1.2-noarch from openSUSE.
>>>
>>> [internet search ...]
>>>
>>> The $internet says that one option is to install and use:
>>> Add 'sphinx_autodoc_typehints' to the extensions list in your conf.py file.
>>> I tried that but now I get:
>>> Extension error:
>>> Unknown event name: autodoc-process-signature
>>
>> The kernel-doc thing is not hooked up in the Sphinx autodoc processing,
>> which is more geared towards Python. I presume sphinx_autodoc_typehints
>> uses autodoc-process-signature which isn't there because the autodoc
>> Sphinx extension isn't loaded, and even if it were, would not be called
>> on kernel-doc handling.
>>

OK, thanks. I'll just try to ignore it. :(

>>
>> BR,
>> Jani.
>>
>>
>>>
>>> Another option is to try a different theme so I reverted to
>>> sphinx_rtd_theme but that didn't help either.
>>>
>>> Does anyone know a good solution to this?
>>>
>>> thanks.
> 

-- 
~Randy

Re: typedef output question/issue?

[Jani Nikula]

On Thu, 21 Nov 2024, Randy Dunlap <rdunlap@infradead.org> wrote:
> On 11/21/24 3:19 AM, Jani Nikula wrote:
>> On Thu, 21 Nov 2024, Jani Nikula <jani.nikula@linux.intel.com> wrote:
>>> On Wed, 20 Nov 2024, Randy Dunlap <rdunlap@infradead.org> wrote:
>>>> Hi,
>>>>
>>>> If I print a typedef in html (make htmldocs) from a .rst file,
>>>> I see:
>>>>
>>>> type dma_cookie_t
>>>>     an opaque DMA cookie
>>>>
>>>> Description
>>>>
>>>> if dma_cookie_t is >0 it’s a DMA request cookie, <0 it’s an error code
>>>>
>>>> ~~~~~~~~~~~~~~~~~~~
>>>>
>>>> If I print the same typedef in man format, it says 'typedef' instead of
>>>> 'type', which is what I expect to see.
>>>
>>> I'm sorry, it's unambigous to me which one you expect.
>> 
>> *ambiguous, obvs!
>
> Sorry about that. I would like to see 'typedef' instead of 'type'.

Right, so looking into it, Sphinx actually has two forms for documenting
types, described at [1]:

.. c:type:: foo_t

.. c:type:: int foo_t

The former is simple, and becomes a generic "type" in rendered
documentation, while the latter can contain a "typedef-like
declaration", and becomes "typedef" in rendered documentation.

So, if you can make kernel-doc emit a proper typedef for the c:type
directive, the output will contain typedef, but otherwise remains just
type. Whether having the actual typedef declaration in the output is
something you also want, is a different matter.

The man page output doesn't go through Sphinx at all, and is just
whatever kernel-doc outputs.

HTH,
Jani.


[1] https://www.sphinx-doc.org/en/master/usage/domains/c.html#directive-c-type


>
> Thanks.
>
>> 
>>>
>>>> man formatted output:
>>>>
>>>> Kernel API(9)                     API Manual                     Kernel API(9)
>>>>
>>>> NAME
>>>>        typedef dma_cookie_t - an opaque DMA cookie
>>>>
>>>> Description
>>>>        if dma_cookie_t is >0 it's a DMA request cookie, <0 it's an error code
>>>>
>>>> November 2024                    dma_cookie_t                    Kernel API(9)
>>>
>>> How do you generate the man pages?
>
> One function or identifier (struct, union, enum, or typedef) at a time.
> Just for testing.
>
> $ scripts/kernel-doc -man -function function_or_identifier file | nroff -man | less
>
> e.g.:
> $ scripts/kernel-doc  -man -function dma_cookie_t  include/linux/dmaengine.h  | nroff -man  | less
>
>>>
>>>> I am using python311-Sphinx 8.0.2-1.2-noarch from openSUSE.
>>>>
>>>> [internet search ...]
>>>>
>>>> The $internet says that one option is to install and use:
>>>> Add 'sphinx_autodoc_typehints' to the extensions list in your conf.py file.
>>>> I tried that but now I get:
>>>> Extension error:
>>>> Unknown event name: autodoc-process-signature
>>>
>>> The kernel-doc thing is not hooked up in the Sphinx autodoc processing,
>>> which is more geared towards Python. I presume sphinx_autodoc_typehints
>>> uses autodoc-process-signature which isn't there because the autodoc
>>> Sphinx extension isn't loaded, and even if it were, would not be called
>>> on kernel-doc handling.
>>>
>
> OK, thanks. I'll just try to ignore it. :(
>
>>>
>>> BR,
>>> Jani.
>>>
>>>
>>>>
>>>> Another option is to try a different theme so I reverted to
>>>> sphinx_rtd_theme but that didn't help either.
>>>>
>>>> Does anyone know a good solution to this?
>>>>
>>>> thanks.
>> 

-- 
Jani Nikula, Intel

Re: typedef output question/issue?

[Randy Dunlap]

Hi Jani,

On 11/21/24 11:28 AM, Jani Nikula wrote:
> On Thu, 21 Nov 2024, Randy Dunlap <rdunlap@infradead.org> wrote:
>> On 11/21/24 3:19 AM, Jani Nikula wrote:
>>> On Thu, 21 Nov 2024, Jani Nikula <jani.nikula@linux.intel.com> wrote:
>>>> On Wed, 20 Nov 2024, Randy Dunlap <rdunlap@infradead.org> wrote:
>>>>> Hi,
>>>>>
>>>>> If I print a typedef in html (make htmldocs) from a .rst file,
>>>>> I see:
>>>>>
>>>>> type dma_cookie_t
>>>>>     an opaque DMA cookie
>>>>>
>>>>> Description
>>>>>
>>>>> if dma_cookie_t is >0 it’s a DMA request cookie, <0 it’s an error code
>>>>>
>>>>> ~~~~~~~~~~~~~~~~~~~
>>>>>
>>>>> If I print the same typedef in man format, it says 'typedef' instead of
>>>>> 'type', which is what I expect to see.
>>>>
>>>> I'm sorry, it's unambigous to me which one you expect.
>>>
>>> *ambiguous, obvs!
>>
>> Sorry about that. I would like to see 'typedef' instead of 'type'.
> 
> Right, so looking into it, Sphinx actually has two forms for documenting
> types, described at [1]:
> 
> .. c:type:: foo_t
> 
> .. c:type:: int foo_t
> 
> The former is simple, and becomes a generic "type" in rendered
> documentation, while the latter can contain a "typedef-like
> declaration", and becomes "typedef" in rendered documentation.
> 
> So, if you can make kernel-doc emit a proper typedef for the c:type

What a big "if"!  Not your problem though.

What this exercise has shown me is that the scripts/kernel-doc processing of
'typedef' is sorely lacking. I.e., "typedef [many options]" is too complex for it. ;)

My test case has 3 typedefs in a row and scripts/kernel-doc sees only the first one
as a typedef, skips the second one, and parses the third one as a macro. (!)


> directive, the output will contain typedef, but otherwise remains just
> type. Whether having the actual typedef declaration in the output is
> something you also want, is a different matter.

Thanks for your assistance.

-- 
~Randy