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 v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags
To:     Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Cc:     Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        Jonathan Corbet <corbet@lwn.net>,
        "Steven Rostedt (VMware)" <rostedt@goodmis.org>,
        Miroslav Benes <mbenes@suse.cz>,
        Petr Mladek <pmladek@suse.com>,
        Sebastian Andrzej Siewior <bigeasy@linutronix.de>,
        linux-kernel@vger.kernel.org
References: <cover.1601467849.git.mchehab+huawei@kernel.org>
 <f1d8fc4bb976f8c25c6fb444b0b675d9a849ba06.1601467849.git.mchehab+huawei@kernel.org>
 <5e19b1d5-8015-c41d-788d-00b121599c6b@linux.vnet.ibm.com>
 <20201001084143.7c6f7836@coco.lan>
From:   Kamalesh Babulal <kamalesh@linux.vnet.ibm.com>
Message-ID: <3c1bca2d-b954-1f48-3cf9-617e01137e99@linux.vnet.ibm.com>
Date:   Thu, 1 Oct 2020 13:57:52 +0530
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: <20201001084143.7c6f7836@coco.lan>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 01/10/20 12:11 pm, Mauro Carvalho Chehab wrote:
> Em Thu, 1 Oct 2020 11:36:53 +0530
> Kamalesh Babulal <kamalesh@linux.vnet.ibm.com> escreveu:
> 
>> On 30/09/20 6:54 pm, Mauro Carvalho Chehab wrote:
>>> There are some c-domain tags that are wrong. While this won't
>>> cause problems with Sphinx < 3.0, this cause troubles with
>>> newer versions, as the C parser won't recognize the contents
>>> of the tag, and will drop it from the output.
>>>
>>> Let's just place them at literal blocks.
>>>   
>>
>> tired with Sphinx v3.2.1, invalid C declaration warnings are not
>> seen with the patch.
> 
> Well, it would be possible to use :c:expr: with Sphinx 3.2.1,
> in order for it to check for invalid C declarations.
> 
> Btw, this is one of the improvements over the last versions: the
> rewritten C parser there is a lot more pedantic with regards to the
> C syntax.
> 
> -
> 
> That's said, the backward-compatibility code I added at 
> Documentation/sphinx/cdomain.py will convert this into a 
> literal markup though, as there's no equivalent tag before 
> Sphinx 3.x.
> 
> As there are still one upstream issue on Sphinx 3.x that requires a fix[1],
> and we don't know yet the issues with :c:expr[2], at least for now, I would 
> avoid adding :c:expr: markups.
> 
> [1] Right now, the C domain is not able to have two names
>     for different types. So, it is not possible to have
>     a struct "foo" and a function "foo".
> 
>     Due to that, while I was able to fix all warnings with
>     Sphinx 2.x build, Sphinx 3.x will still have bogus
>     warnings.
> 
> [2] One of the limitations of :c:expr: is with regards to function
>     prototypes. You can't use it like: :c:expr:`int foo(void);`,
>     as it will complain with the function return type.
> 

Thank you for explaining in detail on the :c:expr: tag. I intended to 
say this patch fixes the warnings seen while using the c-domain tags
and are fixed by converting them into literals. 

-- 
Kamalesh