Re: [PATCH] Documentation: ABI: fix brackets and bracelets

[Jonathan Cameron <jic23@kernel.org>]

On Thu, 11 Jun 2026 13:54:04 +0200
Manuel Ebner <manuelebner@mailbox.org> wrote:

> On Thu, 2026-06-11 at 10:46 +0100, Jonathan Cameron wrote:
> > On Thu, 11 Jun 2026 10:56:21 +0200
> > Manuel Ebner <manuelebner@mailbox.org> wrote:
> >   
> > > Fix missing and needless brackets
> > > Fix missing bracelets
> > > 
> > > Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
> > > ---
> > >  Documentation/ABI/stable/sysfs-class-infiniband      | 4 ++--
> > >  Documentation/ABI/testing/sysfs-bus-iio              | 4 ++--
> > >  Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192   | 2 +-  
> > 
> > Take a look at hos this stuff is routed into upstream.  Each 
> > subsystem 'owns' their own documentation.  So this needs splitting up
> > on a per subsystem basis.  I'll also note that you've only +CC IIO folk
> > so you aren't going to get much review on the rest!  
> 
> I send it to the addresses get_maintainer returned, except the git blame
> ones. How can I find out who to send this to?

Some are easier to track down than others - look up related subsystems
in maintainers + look at anyone who has made significant changes to the files
in question.  However, some folk who work on Docs don't necessarily hang
around so also useful to use lore.kernel.org to see if they have been
on the list recently.  Also sometimes it is a bit fiddlier so look
at the original commits - that lets you find out what the files are associated
with.


INFINIBAND SUBSYSTEM
M:	Jason Gunthorpe <jgg@nvidia.com>
M:	Leon Romanovsky <leonro@nvidia.com>
L:	linux-rdma@vger.kernel.org

DMI/SMBIOS SUPPORT
M:	Jean Delvare <jdelvare@suse.com>
S:	Maintained

gsmi needed a bit of digging:
GOOGLE FIRMWARE DRIVERS
M:	Tzung-Bi Shih <tzungbi@kernel.org>
R:	Brian Norris <briannorris@chromium.org>
R:	Julius Werner <jwerner@chromium.org>
L:	chrome-platform@lists.linux.dev

Similar digging needed for sysfs-uevent, though I could probably have
guessed this one

DRIVER CORE, KOBJECTS, DEBUGFS AND SYSFS
M:	Greg Kroah-Hartman <gregkh@linuxfoundation.org>
M:	"Rafael J. Wysocki" <rafael@kernel.org>
M:	Danilo Krummrich <dakr@kernel.org>
L:	driver-core@lists.linux.dev

IIO was the only one to have a specific match on these files.
It might be worth asking the other folk if they'd be happy to have
the MAINTAINERS entries updated to add one so that others find it easier
in future.

Jonathan

> 
> > A few comments inline.
> >   
> > >  Documentation/ABI/testing/sysfs-firmware-dmi-entries | 2 +-
> > >  Documentation/ABI/testing/sysfs-firmware-gsmi        | 2 +-
> > >  Documentation/ABI/testing/sysfs-uevent               | 2 +-
> > >  6 files changed, 8 insertions(+), 8 deletions(-)
> > > 
> > > diff --git a/Documentation/ABI/stable/sysfs-class-infiniband
> > > b/Documentation/ABI/stable/sysfs-class-infiniband
> > > index 694f23a03a28..e48a0d2fb4e5 100644
> > > --- a/Documentation/ABI/stable/sysfs-class-infiniband
> > > +++ b/Documentation/ABI/stable/sysfs-class-infiniband
> > > @@ -157,8 +157,8 @@ Description:
> > >  		all VLs from this port. This may include packets with errors.
> > >  		This is 64 bit counter.
> > >  
> > > -		port_rcv_packets: (RO) Total number of packets (this may include
> > > -		packets containing Errors. This is 64 bit counter.
> > > +		port_rcv_packets: (RO) Total number of packets, this may include
> > > +		packets containing Errors. This is a 64 bit counter.  
> > Comma doesn't feel like the right choice here.  Perhaps,
> > 
> > 		port_rc_packets: (RO) Total number of packets. May include
> > 		packets containing Errors. This is a 64 bit counter.
> > 
> > Or just add the closing bracket.  
> 
> will do this.
> 
> > >  
> > >  		link_downed: (RO) Total number of times the Port Training state
> > >  		machine has failed the link error recovery process and downed
> > > 
> > > diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > > b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > > index 28be1cabf112..108ea0abbdb6 100644
> > > --- a/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > > +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-ad7192
> > > @@ -16,7 +16,7 @@ Description:
> > >  		In bridge applications, such as strain gauges and load cells,
> > >  		the bridge itself consumes the majority of the current in the
> > >  		system. To minimize the current consumption of the system,
> > > -		the bridge can be disconnected (when it is not being used
> > > +		the bridge can be disconnected when it is not being used
> > >  		using the bridge_switch_en attribute.  
> > 
> > I think intent would be better reflected here by adding the closing )
> > That last bit is kind of a 'by the way' rather than the dominant point of
> > the sentence.  
> 
> 		system. To minimize the current consumption of the system,
> -		the bridge can be disconnected (when it is not being used
> +		the bridge can be disconnected (when it is not being used)
>  		using the bridge_switch_en attribute.
> like this?

Looks good.

> 
> >   
> > >  
> > >  What:		/sys/bus/iio/devices/iio:deviceX/in_voltage2-voltage2_shorted_raw  
> >   
> > > diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi
> > > b/Documentation/ABI/testing/sysfs-firmware-gsmi
> > > index 7a558354c1ee..88ca75d323d1 100644
> > > --- a/Documentation/ABI/testing/sysfs-firmware-gsmi
> > > +++ b/Documentation/ABI/testing/sysfs-firmware-gsmi
> > > @@ -18,7 +18,7 @@ Description:
> > >  
> > >  		/sys/firmware/gsmi/vars:
> > >  
> > > -			This directory has the same layout (and
> > > +			This directory has the same layout and
> > >  			underlying implementation as /sys/firmware/efi/vars.
> > >  			See `Documentation/ABI/*/sysfs-firmware-efi-vars`
> > >  			for more information on how to interact with  
> > I think I'd add the bracket after implementation as this file is about ABI
> > so that's less important than the rest of the sentence.  
> 
> 			This directory has the same layout (and
> - 			underlying implementation as /sys/firmware/efi/vars.
> + 			underlying implementation) as /sys/firmware/efi/vars.
>  			See `Documentation/ABI/*/sysfs-firmware-efi-vars`
>  			for more information on how to interact with
> 
> like this?

yes

Thanks,

Jonathan

> 
> Thanks 
>  manuel