C domain issues when building the Linux Kernel documentation

[mchehab]

Describe the bug

Some :c:function: declarations that are valid in C and worked fine up to Sphinx 2.4 are not properly parsed with Sphinx 3.x for the Linux Kernel documentation.

To Reproduce

Steps to reproduce the behavior:

$ git clone --branch test_cec_sphinx3 git://linuxtv.org/mchehab/experimental.git docs
$ cd docs
# Install Sphinx 3.2.1 via pip
$ make htmldocs

[mchehab]

As building the entire Kernel documentation takes a long time, specially with Sphinx 3.2, I added a patch that will allow showing just the errors I'm noticing:

https://git.linuxtv.org/mchehab/experimental.git/commit/?h=test_cec_sphinx3&id=daaac7f975b63b34536e62aea18ecdb66bc4c6a1

With such patch applied, the issue can be reproduced with:

$ make htmldocs SPHINXDIRS=foo_example

Instead of parsing the valid ReST file, Sphinx 3.2 produce those warnings:

/devel/v4l/docs/Documentation/foo_example/parsed_i915_perf_c.rst:307: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "*". [error at 68]
  int append_oa_status (struct i915_perf_stream * stream, char __user * buf, size_t count, size_t * offset, enum drm_i915_perf_record_type type)
  --------------------------------------------------------------------^
/devel/v4l/docs/Documentation/foo_example/parsed_i915_perf_c.rst:340: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "*". [error at 68]
  int append_oa_sample (struct i915_perf_stream * stream, char __user * buf, size_t count, size_t * offset, const u8 * report)
  --------------------------------------------------------------------^
/devel/v4l/docs/Documentation/foo_example/parsed_i915_perf_c.rst:375: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "*". [error at 74]
  int gen8_append_oa_reports (struct i915_perf_stream * stream, char __user * buf, size_t count, size_t * offset)
  --------------------------------------------------------------------------^
/devel/v4l/docs/Documentation/foo_example/parsed_i915_perf_c.rst:412: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "*". [error at 64]
  int gen8_oa_read (struct i915_perf_stream * stream, char __user * buf, size_t count, size_t * offset)
  ----------------------------------------------------------------^
/devel/v4l/docs/Documentation/foo_example/parsed_i915_perf_c.rst:448: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "*". [error at 74]
  int gen7_append_oa_reports (struct i915_perf_stream * stream, char __user * buf, size_t count, size_t * offset)
  --------------------------------------------------------------------------^
/devel/v4l/docs/Documentation/foo_example/parsed_i915_perf_c.rst:485: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "*". [error at 64]
  int gen7_oa_read (struct i915_perf_stream * stream, char __user * buf, size_t count, size_t * offset)
  ----------------------------------------------------------------^
/devel/v4l/docs/Documentation/foo_example/parsed_i915_perf_c.rst:565: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "*". [error at 64]
  int i915_oa_read (struct i915_perf_stream * stream, char __user * buf, size_t count, size_t * offset)
  ----------------------------------------------------------------^
/devel/v4l/docs/Documentation/foo_example/parsed_i915_perf_c.rst:693: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "*". [error at 56]
  ssize_t i915_perf_read (struct file * file, char __user * buf, size_t count, loff_t * ppos)
  --------------------------------------------------------^
/devel/v4l/docs/Documentation/foo_example/parsed_i915_perf_c.rst:963: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "*". [error at 66]
  int read_properties_unlocked (struct i915_perf * perf, u64 __user * uprops, u32 n_props, struct perf_open_properties * props)
  ------------------------------------------------------------------^

To give some extra context, at the Linux Kernel build, a Sphinx extension calls the ./scripts/kernel-doc script, which extracts documentation markups from C and H files and produces a RST output like this:

$ ./scripts/kernel-doc ./drivers/gpu/drm/i915/i915_perf.c >Documentation/foo_example/parsed_i915_perf_c.rst

Right now, if built with Sphinx 3.2, we're getting ~1700 warnings, several of them similar to the above.

[jakobandersen]

The parser gets confused by the __user annotation. I guess it is (macro for) an attribute? If you to conf.py adds something like

c_id_attributes = ["__user"]

then it should parse correctly. (see also https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-c_id_attributes)

[mchehab]

The parser gets confused by the __user annotation. I guess it is (macro for) an attribute? If you to conf.py adds something like

c_id_attributes = ["__user"]

then it should parse correctly. (see also https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-c_id_attributes)

It is impossible to maintain something like that. The Kernel has hundreds (or maybe thousands) of macros, and every time newer ones are added.

For example, if you try to build the admin-guide with:

   $ make cleandocs;make htmldocs SPHINXDIRS=admin-guide

That produces several errors due to other macros:

./include/linux/bootconfig.h:142: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 25]
    xbc_array_for_each_value ( anode,  value)
    -------------------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expecting "(" in parameters. [error at 32]
    xbc_array_for_each_value ( anode,  value)
    --------------------------------^

./include/linux/bootconfig.h:153: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 24]
    xbc_node_for_each_child ( parent,  child)
    ------------------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expecting "(" in parameters. [error at 32]
    xbc_node_for_each_child ( parent,  child)
    --------------------------------^

./include/linux/bootconfig.h:173: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 30]
    xbc_node_for_each_array_value ( node,  key,  anode,  value)
    ------------------------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expecting "(" in parameters. [error at 36]
    xbc_node_for_each_array_value ( node,  key,  anode,  value)
    ------------------------------------^

./include/linux/bootconfig.h:186: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 28]
    xbc_node_for_each_key_value ( node,  knode,  value)
    ----------------------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expecting "(" in parameters. [error at 34]
    xbc_node_for_each_key_value ( node,  knode,  value)
    ----------------------------------^

./include/linux/bootconfig.h:197: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 23]
    xbc_for_each_key_value ( knode,  value)
    -----------------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expecting "(" in parameters. [error at 30]
    xbc_for_each_key_value ( knode,  value)
    ------------------------------^

./fs/pstore/blk.c:176: WARNING: Duplicate C declaration, also defined in 'pstore-blk'.
Declaration is 'int register_pstore_device (struct pstore_device_info * dev)'.
./fs/pstore/blk.c:433: WARNING: Duplicate C declaration, also defined in 'pstore-blk'.
Declaration is 'int register_pstore_blk (struct pstore_blk_info * info)'.
./include/linux/pstore_blk.h:1: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 25]
  pstore_blk_panic_write_op
  -------------------------^
./include/linux/pstore_blk.h:44: WARNING: Duplicate C declaration, also defined in 'pstore-blk'.
Declaration is 'pstore_device_info'.
./include/linux/rio_drv.h:294: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 11]
    RIO_DEVICE ( dev,  ven)
    -----------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expecting "(" in parameters. [error at 16]
    RIO_DEVICE ( dev,  ven)
    ----------------^

./drivers/rapidio/rio-access.c:43: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 13]
    RIO_LOP_READ ( size,  type,  len)
    -------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expecting "(" in parameters. [error at 19]
    RIO_LOP_READ ( size,  type,  len)
    -------------------^

./drivers/rapidio/rio-access.c:60: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 14]
    RIO_LOP_WRITE ( size,  type,  len)
    --------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expecting "(" in parameters. [error at 20]
    RIO_LOP_WRITE ( size,  type,  len)
    --------------------^

./drivers/rapidio/rio-access.c:95: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 12]
    RIO_OP_READ ( size,  type,  len)
    ------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expecting "(" in parameters. [error at 18]
    RIO_OP_READ ( size,  type,  len)
    ------------------^

./drivers/rapidio/rio-access.c:113: WARNING: Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
  Invalid C declaration: Expected identifier in nested name. [error at 13]
    RIO_OP_WRITE ( size,  type,  len)
    -------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
  Error in declarator or parameters
  Invalid C declaration: Expecting "(" in parameters. [error at 19]
    RIO_OP_WRITE ( size,  type,  len)
    -------------------^

[jakobandersen]

This particular config var is only for IDs that are in positions where an attribute is expected, not for general macro substitution. I'm not familiar enough with the kernel to judge the other declarations you posted without context, but many of them look like actual macro definitions for which the c:macro directive should work.

[mchehab]

This particular config var is only for IDs that are in positions where an attribute is expected, not for general macro substitution. I'm not familiar enough with the kernel to judge the other declarations you posted without context, but many of them look like actual macro definitions for which the c:macro directive should work.

The kernel-doc markup is defined here:
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html

There's no distinction for it when a markup is for a function, typedef or macros, and that's by purpose: the users of the Kernel internal APIs shouldn't need to take any care about how something is implemented. It is common that some implementations to be re-written, moving from functions into macros or vice-versa.

[jakobandersen]

From a brief look in scripts/kernel-doc it looks like it indeed already detects the exact type of declaration, but outputs a lot of them with .. c:function:: (e.g., see dump_function and output_function_rst). Unfortunately my Perl skills are not up to proposing concrete changes to fix it at this time.

The distinction between macros and functions in the C domain has always been there, but the function parsing was on one hand relaxed enough to eat macros as well, but not detailed enough to parse function declarations if they became a bit too complex. Hence the large changes to the parser.

[mchehab]

From a brief look in scripts/kernel-doc it looks like it indeed already detects the exact type of declaration, but outputs a lot of them with .. c:function:: (e.g., see dump_function and output_function_rst). Unfortunately my Perl skills are not up to proposing concrete changes to fix it at this time.

The distinction between macros and functions in the C domain has always been there, but the function parsing was on one hand relaxed enough to eat macros as well, but not detailed enough to parse function declarations if they became a bit too complex. Hence the large changes to the parser.

It detect some things, but it won't detect things like __atribute macros. We have several Kernel internal macros for different attributes (like __printf() macro for gnu_printf attributes), nor address space ones like __user. We also use lots of other macros, like __maybe_inline as part of the function declaration or the function parameters.

We need to use lots of such macros, and from time to time, newer ones gets added, in order to simplify things, to help static analyzers to check for errors and to make the Kernel compatible with different compilers, compiler versions, configure options and toolchains.

So, at least for the Linux Kernel, a relaxed function parsing works a lot better.

It sounds to me that, while there's nothing like a c:function_relaxed tag is added in Sphinx, the only viable alternative would be to use just c:macro markups for all functions, e. g.:

https://lore.kernel.org/linux-doc/14bed823b6c6f290705debfe42dfd6bed21c3231.1601022949.git.mchehab+huawei@kernel.org/T/#u

I didn't check yet how the C function indexes and cross-references will work if we use that, though.

[jakobandersen]

I gave it a go and made some potential fixes: https://github.com/jakobandersen/linux_docs

• It looks like it's just 13 c_id_attributes entries are needed.
• I think I also got kernel-doc to output c:macro, c:type, and c:function`` correctly.
• In v3.2 a new configuration variable c_allow_pre_v3 was added to try and alleviate some of the compatibility problems, so old style type directives and roles are parsed. For now, this functionality is deprecated to be removed again in v5. In the linked branch the deprecation warnings are silenced.
• A few manual fixes in some files.

With that I get 1323 lines with WARNING, of which almost all are duplicate declaration warnings:

      1 WARNING: Duplicate C declaration, also defined in 'driver-api/80211/mac80211'.
      1 WARNING: Duplicate C declaration, also defined in 'driver-api/devfreq'.
      1 WARNING: Duplicate C declaration, also defined in 'driver-api/media/drivers/frontends'.
      1 WARNING: Duplicate C declaration, also defined in 'driver-api/miscellaneous'.
      1 WARNING: Duplicate C declaration, also defined in 'gpu/drm-kms-helpers'.
      1 WARNING: Duplicate C declaration, also defined in 'gpu/drm-uapi'.
      1 WARNING: Duplicate C declaration, also defined in 'networking/statistics'.
      1 WARNING: Invalid C declaration: Expected end of definition. [error at 43]
      1 WARNING: Invalid C declaration: Expected end of definition. [error at 61]
      1 WARNING: Invalid C declaration: Expected end of definition. [error at 62]
      1 WARNING: Invalid C declaration: Expected end of definition. [error at 81]
      1 WARNING: Invalid C declaration: Expected end of definition. [error at 95]
      1 WARNING: Invalid C declaration: Expected identifier, ')', or ',' in macro parameter list. [error at 31]
      1 WARNING: The kernel documentation build process
      1 WARNING: undefined label: documentation/userspace-api/spec_ctrl.rst (if the link has no caption the label must precede a section header)
      1 WARNING: Unparseable C cross-reference: 'calling snd_card_free'
      1 WARNING: Unparseable C cross-reference: 'cpu_to_be32p(), che prende un puntatore\nad un tipo, e ritorna il valore convertito. L\'altra variante per\nla famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s'
      2 WARNING: document isn't included in any toctree
      2 WARNING: Duplicate C declaration, also defined in 'core-api/printk-basics'.
      2 WARNING: Duplicate C declaration, also defined in 'driver-api/usb/gadget'.
      2 WARNING: Duplicate C declaration, also defined in 'gpu/drm-kms'.
      2 WARNING: Duplicate C declaration, also defined in 'PCI/pci'.
      2 WARNING: Invalid C declaration: Expected end of definition. [error at 35]
      2 WARNING: Invalid C declaration: Expected identifier in nested name, got keyword: typedef [error at 7]
      2 WARNING: Unparseable C cross-reference: 'struct'
      3 WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
      3 WARNING: dvipng command 'dvipng' cannot be run (needed for math display), check the imgmath_dvipng setting
      3 WARNING: Error in declarator or parameters
     10 WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
     32 WARNING: Duplicate C declaration, also defined in 'core-api/workqueue'.
     33 WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
     40 WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
     54 WARNING: Duplicate C declaration, also defined in 'driver-api/scsi'.
     59 WARNING: Duplicate C declaration, also defined in 'driver-api/media/v4l2-async'.
    118 WARNING: Duplicate C declaration, also defined in 'core-api/genericirq'.
    157 WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
    250 WARNING: Duplicate C declaration, also defined in 'foo_example/parsed_i915_perf_c'.
    528 WARNING: Duplicate C declaration, also defined in 'sound/kernel-api/alsa-driver-api'.

[mchehab]

I gave it a go and made some potential fixes: https://github.com/jakobandersen/linux_docs

Thanks for doing that!

Could you please add a description on your patches and add your Signed-off-by:

https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin

At least some of them makes sense to me.

* It looks like it's just 13 `c_id_attributes` entries are needed.

Not bad. I was expecting the need of also place typedef macros, like u32, s32, __u32, _be32, ...
We have several of them.

* I think I also got kernel-doc to output `c:macro`, `c:type`, and ` `c:function`` correctly.

I'll give it a try.

* In v3.2 a new configuration variable `c_allow_pre_v3` was added to try and alleviate some of the compatibility problems, so old style type directives and roles are parsed. For now, this functionality is deprecated to be removed again in v5. In the linked branch the deprecation warnings are silenced.

I'm in doubt of using it. We use the cdomain.py extension for Kernel < 3.x. I wrote a patch for it (not fully tested yet), that teaches it how to convert Sphinx 3.x C domain syntax into legacy one:

https://git.linuxtv.org/mchehab/experimental.git/commit/?h=sphinx3-fixes&id=7c4c0769d3722a360dc0cca94bcfeeba0104c9cf

If this works fine, this could be a a cleaner approach, as we won't need to deal with deprecation later. Otherwise, we could apply your patch for a couple of Kernel releases, until all old style calls are still in usage.

* A few manual fixes in some files.

Yeah, yesterday, I also did some of those myself. Unfortunately, fixing the remaining issues is painful, as Sphinx 3.2.1 doc build is taking almost 5 minutes on a Xeon workstation with 12 cores.

157 WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.

This is something that I'm yet to see a good solution.

See, the Kernel documentation has translations for some languages, being Italian and Chinese the more actively maintained ones. It is very common to have reference collisions between the translations and the main documentation. That happens not only at C domain, but also for all other references.

The best here would be to have something at the file which contains the main index file for each translation, saying that all cross-references will belong to a different namespace. Before the conversion from DocBook, we used to have divisions to avoid such namespace collisions. Each division would have its own xref namespace. Could something like that be done with Sphinx?

[mchehab]

With that I get 1323 lines with WARNING, of which almost all are duplicate declaration warnings:

      1 WARNING: Duplicate C declaration, also defined in 'driver-api/80211/mac80211'.
      1 WARNING: Duplicate C declaration, also defined in 'driver-api/devfreq'.
      1 WARNING: Duplicate C declaration, also defined in 'driver-api/media/drivers/frontends'.
      1 WARNING: Duplicate C declaration, also defined in 'driver-api/miscellaneous'.
      1 WARNING: Duplicate C declaration, also defined in 'gpu/drm-kms-helpers'.
      1 WARNING: Duplicate C declaration, also defined in 'gpu/drm-uapi'.
      1 WARNING: Duplicate C declaration, also defined in 'networking/statistics'.
      1 WARNING: Invalid C declaration: Expected end of definition. [error at 43]
      1 WARNING: Invalid C declaration: Expected end of definition. [error at 61]
      1 WARNING: Invalid C declaration: Expected end of definition. [error at 62]
      1 WARNING: Invalid C declaration: Expected end of definition. [error at 81]
      1 WARNING: Invalid C declaration: Expected end of definition. [error at 95]
      1 WARNING: Invalid C declaration: Expected identifier, ')', or ',' in macro parameter list. [error at 31]
      1 WARNING: The kernel documentation build process
      1 WARNING: undefined label: documentation/userspace-api/spec_ctrl.rst (if the link has no caption the label must precede a section header)
      1 WARNING: Unparseable C cross-reference: 'calling snd_card_free'
      1 WARNING: Unparseable C cross-reference: 'cpu_to_be32p(), che prende un puntatore\nad un tipo, e ritorna il valore convertito. L\'altra variante per\nla famiglia di conversioni "in-situ", come :c:func:`cpu_to_be32s'
      2 WARNING: document isn't included in any toctree
      2 WARNING: Duplicate C declaration, also defined in 'core-api/printk-basics'.
      2 WARNING: Duplicate C declaration, also defined in 'driver-api/usb/gadget'.
      2 WARNING: Duplicate C declaration, also defined in 'gpu/drm-kms'.
      2 WARNING: Duplicate C declaration, also defined in 'PCI/pci'.
      2 WARNING: Invalid C declaration: Expected end of definition. [error at 35]
      2 WARNING: Invalid C declaration: Expected identifier in nested name, got keyword: typedef [error at 7]
      2 WARNING: Unparseable C cross-reference: 'struct'
      3 WARNING: Duplicate C declaration, also defined in 'admin-guide/pstore-blk'.
      3 WARNING: dvipng command 'dvipng' cannot be run (needed for math display), check the imgmath_dvipng setting
      3 WARNING: Error in declarator or parameters
     10 WARNING: Duplicate C declaration, also defined in 'driver-api/infrastructure'.
     32 WARNING: Duplicate C declaration, also defined in 'core-api/workqueue'.
     33 WARNING: Duplicate C declaration, also defined in 'core-api/kernel-api'.
     40 WARNING: Duplicate C declaration, also defined in 'driver-api/firmware/request_firmware'.
     54 WARNING: Duplicate C declaration, also defined in 'driver-api/scsi'.
     59 WARNING: Duplicate C declaration, also defined in 'driver-api/media/v4l2-async'.
    118 WARNING: Duplicate C declaration, also defined in 'core-api/genericirq'.
    157 WARNING: Duplicate C declaration, also defined in 'translations/it_IT/kernel-hacking/locking'.
    250 WARNING: Duplicate C declaration, also defined in 'foo_example/parsed_i915_perf_c'.
    528 WARNING: Duplicate C declaration, also defined in 'sound/kernel-api/alsa-driver-api'.

I'm starting to suspect that several of those warnings are due to some incompatibility between the new C parser code and kerneldoc extensions.

As I described before, most C markups at the Linux Kernel are generated via scripts/kerneldoc. Such script is called by a Sphinx extension:

https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/sphinx/kerneldoc.py?h=sphinx3-fixes

Now, running this command against my last git branch (https://git.linuxtv.org/mchehab/experimental.git/log/?h=sphinx3-fixes):

$ touch lib/math/div64.c Documentation/core-api/kernel-api.rst; make O=/devel/v4l/docs/sphinx3 SPHINXDIRS=core-api htmldocs 

causes Sphinx to warn about several duplicated duplications, like those:

.../Documentation/core-api/kernel-api:171: ../lib/math/div64.c:72: WARNING: Duplicate C declaration, also defined in 'kernel-api'.
Declaration is 'div_s64_rem'.
.../Documentation/core-api/kernel-api:171: ../lib/math/div64.c:103: WARNING: Duplicate C declaration, also defined in 'kernel-api'.
Declaration is 'div64_u64_rem'.
.../Documentation/core-api/kernel-api:171: ../lib/math/div64.c:143: WARNING: Duplicate C declaration, also defined in 'kernel-api'.
Declaration is 'div64_u64'.
.../Documentation/core-api/kernel-api:171: ../lib/math/div64.c:171: WARNING: Duplicate C declaration, also defined in 'kernel-api'.
Declaration is 'div64_s64'.

The Documentation/core-api/kernel-api.rst includes lib/math/div64.c just once, and there's just one markup for each of the above functions. So, I can't identify where the "duplicated" declaration came from.

I'm starting to suspect that it could be due to some problems with the part of the code at c.py that checks for duplication. It sounds that, as the actual definition came from an "included" file, it doesn't consider them to belong to the kernel-api.rst and reports them as duplicated.

[mchehab]

I'm starting to suspect that it could be due to some problems with the part of the code at c.py that checks for duplication. It sounds that, as the actual definition came from an "included" file, it doesn't consider them to belong to the kernel-api.rst and reports them as duplicated.

Never mind. False alarm. After adding some additional logs at c.py, I was able to identify that the duplication came from a different implementation, also included by the same file. Basically, both
lib/math/div64.c and include/linux/math64.h implements them, with different algorithms.

[mchehab]

I was able to solve most warnings. There are just 10 warnings now after my work.

Yet, some of them indeed seems to be a Sphinx C domain bug, that it is generating duplicated cross references for different symbol types.

How to reproduce it

With this patch applied:

https://git.linuxtv.org/mchehab/experimental.git/commit/?h=sphinx_issues&id=82d1234133b0beaf62f00039efa8220d2cce2129

run, with Sphinx 3.2.1:

$ make SPHINXDIRS=foobar htmldocs
/devel/v4l/docs/Documentation/foobar/broken.rst:26: WARNING: Duplicate C declaration, also defined in 'broken'.
Declaration is 'pwm_capture2'.
/devel/v4l/docs/Documentation/foobar/broken2.rst:25: WARNING: Duplicate C declaration, also defined in 'broken2'.
Declaration is 'int pwm_capture (struct pwm_device * pwm, struct pwm_capture * result, unsigned long timeout)'.

At the C language, is is OK to have a function with the same name as a struct. While this is not a common pattern, there are some widely used functions and structs at the Linux Kernel with identical names.