linux-kernel - [PATCH 0/2] docs: Add automatic cross-reference for C types

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <20200903005747.3900333-1-nfraprado@protonmail.com>
Date:   Thu, 03 Sep 2020 00:58:09 +0000
From:   Nícolas F. R. A. Prado 
        <nfraprado@...tonmail.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        lkcamp@...ts.libreplanetbr.org, andrealmeid@...labora.com
Subject: [PATCH 0/2] docs: Add automatic cross-reference for C types

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.

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.

After getting this merged I intend to start removing the occurrences of :c:type.

Thanks,
Nícolas

Nícolas F. R. A. Prado (2):
  docs: Add automatic cross-reference for C types
  kernel-doc: Update "cross-referencing from rST" section to use
    automarkup

 Documentation/doc-guide/kernel-doc.rst | 33 ++++++++++++-----------
 Documentation/sphinx/automarkup.py     | 37 +++++++++++++++++---------
 2 files changed, 41 insertions(+), 29 deletions(-)

-- 
2.28.0