Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Subject: Re: [PATCH 0/2] docs: Add automatic cross-reference for C types
To:     =?UTF-8?B?TsOtY29sYXMgRi4gUi4gQS4gUHJhZG8=?= 
        <nfraprado@protonmail.com>, Jonathan Corbet <corbet@lwn.net>
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        lkcamp@lists.libreplanetbr.org, andrealmeid@collabora.com
References: <20200903005747.3900333-1-nfraprado@protonmail.com>
From:   Randy Dunlap <rdunlap@infradead.org>
Message-ID: <1a03c65e-6fbc-25f9-e553-61259a310f29@infradead.org>
Date:   Wed, 2 Sep 2020 19:43:08 -0700
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.11.0
MIME-Version: 1.0
In-Reply-To: <20200903005747.3900333-1-nfraprado@protonmail.com>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 8bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

On 9/2/20 5:58 PM, Nícolas F. R. A. Prado 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.
> 
> 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.

There also isn't any file name scsi_typedefs.h any longer,
so maybe we can update scsi_mid_low_api.rst as well.

Thanks.

> 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(-)
> 


-- 
~Randy