Re: [PATCH 05/12] pci doc: convert PCI/MSI-HOWTO.txt to rst format

From: Matthew Wilcox <willy@infradead.org>
To: Changbin Du <changbin.du@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
	Bjorn Helgaas <bhelgaas@google.com>,
	linux-pci@vger.kernel.org, linux-doc@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: Re: [PATCH 05/12] pci doc: convert PCI/MSI-HOWTO.txt to rst format
Date: Fri, 29 Mar 2019 21:00:09 -0700	[thread overview]
Message-ID: <20190330040009.GY10344@bombadil.infradead.org> (raw)
In-Reply-To: <20190329160413.4293-6-changbin.du@gmail.com>

On Sat, Mar 30, 2019 at 12:04:06AM +0800, Changbin Du wrote:
> @@ -1,13 +1,18 @@
> -		The MSI Driver Guide HOWTO
> -	Tom L Nguyen tom.l.nguyen@intel.com
> -			10/03/2003
> -	Revised Feb 12, 2004 by Martine Silbermann
> -		email: Martine.Silbermann@hp.com
> -	Revised Jun 25, 2004 by Tom L Nguyen
> -	Revised Jul  9, 2008 by Matthew Wilcox <willy@linux.intel.com>
> -		Copyright 2003, 2008 Intel Corporation
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: <isonum.txt>
> +
> +==========================
> +The MSI Driver Guide HOWTO
> +==========================
> +
> +:Authors: - Tom L Nguyen <tom.l.nguyen@intel.com> 10/03/2003
> +          - Revised Feb 12, 2004 by Martine Silbermann <Martine.Silbermann@hp.com>
> +	  - Revised Jun 25, 2004 by Tom L Nguyen
> +	  - Revised Jul  9, 2008 by Matthew Wilcox <willy@linux.intel.com>
> +	    Copyright 2003, 2008 Intel Corporation

The copyright line doesn't work quite the way it should in the rendered HTML.

It seems to me it should be:

:Copyright: 2003, 2008 Intel Corporation

Tom has used an ambiguous date format; given it appeared in the tree
in December 2003, I suspect he's used middle-endian format.  It doesn't
really seem relevant to have the dates here any more, so we could skip
including them.  Also, none of these email addresses work, so perhaps
just drop those too.

:Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox

>  1. About this guide
> +===================

Should we drop the numbering of sections as part of this conversion?
I'd be inclined to.

>  4.2 Using MSI
> +-------------
>  
>  Most of the hard work is done for the driver in the PCI layer.  The driver
>  simply has to request that the PCI layer set up the MSI capability for this
>  device.
>  
>  To automatically use MSI or MSI-X interrupt vectors, use the following
> -function:
> +function::
>  
>    int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
>  		unsigned int max_vecs, unsigned int flags);

This should really be turned into kernel-doc and moved to pci.h, but
that seems like an awfully large amount of work to ask you to do when
you're already doing so much to improve the situation.

This is also a really bad document.  It has three audiences; people
configuring their kernel, people writing device drivers and people trying
to debug why their kernel doesn't work.  Again, that's not on you to
fix, but it's pretty frustrating to see so much good information so
badly organised.