Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Wed, 12 Jul 2023 07:42:58 +0200
From:   Mauro Carvalho Chehab <mchehab@kernel.org>
To:     Randy Dunlap <rdunlap@infradead.org>
Cc:     Akira Yokosawa <akiyks@gmail.com>, amd-gfx@lists.freedesktop.org,
        corbet@lwn.net, dri-devel@lists.freedesktop.org,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: scripts/kernel-doc does not handle duplicate struct & function
 names (e.g., in amdgpu)
Message-ID: <20230712074258.3602b6e8@coco.lan>
In-Reply-To: <58cafdc0-0209-cfdd-c8e0-2dd25d73a184@infradead.org>
References: <b5ebc891-ee63-1638-0377-7b512d34b823@infradead.org>
        <0475d177-4c01-0988-0b34-3099dd703498@gmail.com>
        <58cafdc0-0209-cfdd-c8e0-2dd25d73a184@infradead.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

Em Tue, 11 Jul 2023 20:45:18 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

> On 7/11/23 20:32, Akira Yokosawa wrote:
> > Hi Randy,
> >   
> >> [just documenting this for posterity or in case someone wants to fix it.]
> >>
> >> In drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c, one can find both
> >>
> >> struct amdgpu_vm_tlb_seq_cb {...};
> >>
> >> and
> >> static void amdgpu_vm_tlb_seq_cb(...)
> >>
> >> Of course C has no problem with this, but kernel-doc reports:
> >>
> >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:833: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/driver-core:115.
> >>
> >> And of course, if the name of one of them is changed, kernel-doc is all happy...
> >> not that I am suggesting that one of them should be changed.
> >>
> >> I just want to make people aware of this. (or maybe people are already aware of this?)  
> > 
> > The duplicate warning is emitted from Sphinx, not kernel-doc.
> > 
> > This is a bug of Sphinx >=3.1, first reported by Mauro back in September 2020 at:
> > 
> >     https://github.com/sphinx-doc/sphinx/issues/8241
> > 
> > It was closed when a local fix was presented.  Unfortunately, it was not
> > merged at the time and a subsequent pull request was opened at:
> > 
> >     https://github.com/sphinx-doc/sphinx/pull/8313
> > 
> > It is not merged yet and carries a milestone of Sphinx 7.x.
> > 
> > Looks like we need to wait patiently.
> > 
> >         Thanks, Akira  
> 
> Ooooh, thanks for your assistance.  Waiting.... :)

Yeah, we've been waiting this since Sphinx version 3.x times :-(

It seems that applying the fix would break an extension
(intersphinx). We don't use at the Kernel, so it won't affect
us, but it seems to be a popular extension, as it allows one
web server to have cross-references to Sphinx docs produced
elsewhere. Btw, such extension could be interesting on partial
doc builds (e. g. make SPHNXDIRS="foo_dir" htmldocs), as the
non-existing cross-references would be pointing, for instance,
to the docs stored at kernel.doc latest docs.

Btw, I'm still using version 2.4.4 when building the docs
to avoid the wrong duplicate warnings with 3.1+ due to this bug.

Thanks,
Mauro