On Thu, 03 Sep 2020 00:58:09 +0000 Nícolas F. R. A. Prado <nfraprado@xxxxxxxxxxxxxx> wrote: > In order to cross-reference C types in the documentation, Sphinx > requires the syntax :c:type:`type_name`, or even :c:type:`struct > type_name <type_name>` in order to have the link text different from the > target text. > This patch series removes the need for that markup. > > The first commit extends the automarkup script to enable automatic > cross-reference of C types by matching any "struct|union|enum|typedef type_name" > expression. > This makes the documentation's plain text cleaner and adds cross-reference to > types without any additional effort by the author. > > The second commit updates the "Cross-referencing from > reStructuredText" section in Documentation/doc-guide/kernel-doc.rst > to reflect that no additional syntax is needed when cross-referencing both types > and functions anymore. So I've looked this over, applied it, looked at how the output changes, and generally put an untoward amount of effort into finding something to grumble about. I failed. This is a great change - thanks for stepping up and doing it! > When testing this, I did find an edge-case from the output of > Documentation/output/scsi/scsi_mid_low_api.rst on the "typedef struct scsi_cmnd > Scsi_Cmnd;", where 'typedef struct' is being identified as a reference, but > there isn't any named 'struct', so it renders bold. > I thought of adding an ignore_names list just like there is one for functions, > with 'struct' in it, to workaround this edge case, but since it was the only > one I found, and also because it was unclear what the desired output was > (cross-reference 'struct scsi_cmnd' or leave the whole expression as plain text) > I wanted to get some feedback beforehand. As Randy pointed out, the documentation in question is obsolete and incorrect anyway; there's really not much that can be done in the docs build system to fix *that*. I'm not going to worry about this particular glitch. If you felt so inspired, a patch to the SCSI maintainers just removing that paragraph might be well received. I'm going to go ahead and push this out to linux-next; we'll see if anything explodes from there. Thanks, jon
