linux-kernel - Re: [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain tags

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-prev] [thread-next>] [day] [month] [year] [list]

Date:   Thu, 1 Oct 2020 08:41:43 +0200
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Kamalesh Babulal <kamalesh@...ux.vnet.ibm.com>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>,
        "Steven Rostedt (VMware)" <rostedt@...dmis.org>,
        Miroslav Benes <mbenes@...e.cz>,
        Petr Mladek <pmladek@...e.com>,
        Sebastian Andrzej Siewior <bigeasy@...utronix.de>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v4 23/52] docs: trace-uses.rst: remove bogus c-domain
 tags

Em Thu, 1 Oct 2020 11:36:53 +0530
Kamalesh Babulal <kamalesh@...ux.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.


> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>  
> 
> Reviewed-by: Kamalesh Babulal <kamalesh@...ux.vnet.ibm.com>

Thanks!

Mauro