Re: typedef output question/issue?

[Jani Nikula <jani.nikula@linux.intel.com>]

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