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:   Fri, 18 Nov 2022 13:58:22 +0100
From:   Peter Zijlstra <peterz@infradead.org>
To:     "Ahmed S. Darwish" <darwi@linutronix.de>
Cc:     Bjorn Helgaas <helgaas@kernel.org>,
        Thomas Gleixner <tglx@linutronix.de>,
        LKML <linux-kernel@vger.kernel.org>, x86@kernel.org,
        Joerg Roedel <joro@8bytes.org>, Will Deacon <will@kernel.org>,
        linux-pci@vger.kernel.org, Bjorn Helgaas <bhelgaas@google.com>,
        Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>,
        Marc Zyngier <maz@kernel.org>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        Jason Gunthorpe <jgg@mellanox.com>,
        Dave Jiang <dave.jiang@intel.com>,
        Alex Williamson <alex.williamson@redhat.com>,
        Kevin Tian <kevin.tian@intel.com>,
        Dan Williams <dan.j.williams@intel.com>,
        Logan Gunthorpe <logang@deltatee.com>,
        Ashok Raj <ashok.raj@intel.com>, Jon Mason <jdmason@kudzu.us>,
        Allen Hubbe <allenbh@gmail.com>,
        Reinette Chatre <reinette.chatre@intel.com>,
        Michael Ellerman <mpe@ellerman.id.au>,
        Christophe Leroy <christophe.leroy@csgroup.eu>,
        linuxppc-dev@lists.ozlabs.org, corbet@lwn.net
Subject: Re: [patch 23/39] PCI/MSI: Move pci_alloc_irq_vectors_affinity() to
 api.c
Message-ID: <Y3eBbgjOq5EXnBQB@hirez.programming.kicks-ass.net>
References: <20221111122014.927531290@linutronix.de>
 <20221116162322.GA1115421@bhelgaas>
 <Y3d7xJ5hvhxlRrOE@lx-t490>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <Y3d7xJ5hvhxlRrOE@lx-t490>
Precedence: bulk

On Fri, Nov 18, 2022 at 01:34:12PM +0100, Ahmed S. Darwish wrote:
> On Wed, Nov 16, 2022 at 10:23:22AM -0600, Bjorn Helgaas wrote:
> > On Fri, Nov 11, 2022 at 02:54:51PM +0100, Thomas Gleixner wrote:
> ...
> > > +
> > > +/**
> > > + * pci_alloc_irq_vectors_affinity() - Allocate multiple device interrupt
> > > + *                                    vectors with affinity requirements
> > > + * @dev:      the PCI device to operate on
> > > + * @min_vecs: minimum required number of vectors (must be >= 1)
> > > + * @max_vecs: maximum desired number of vectors
> > > + * @flags:    allocation flags, as in pci_alloc_irq_vectors()
> > > + * @affd:     affinity requirements (can be %NULL).
> > > + *
> > > + * Same as pci_alloc_irq_vectors(), but with the extra @affd parameter.
> > > + * Check that function docs, and &struct irq_affinity, for more details.
> >
> > Is "&struct irq_affinity" some kernel-doc syntax, or is the "&"
> > superfluous?
> >
> 
> Hmmm, I stole it from Documentation/doc-guide/kernel-doc.rst. htmldoc
> parses it and generates a link to the referenced structure's kernel-doc.
> 
> But, yeah, this was literally the first usage of such a doc pattern in
> the entire kernel's C code :)

Perhaps then not start with it and instead try and convince John to make
his script more clever -- this same script already recognises functions
by their () suffix, might as well also key off the 'struct' keyword, no?

This is a Code comment, to be read in a text editor. That & is a syntax
error.