linux-kernel - Re: [PATCH] Documentation: sysfs-pps: Fix `Description:`s

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] [day] [month] [year] [list]
Message-ID: <7f771c56-808d-4142-90ac-f0c949d7a3b6@sch.bme.hu>
Date: Wed, 8 Oct 2025 23:11:48 +0200
From: Bence Csókás <bence98@....bme.hu>
To: Jonathan Corbet <corbet@....net>, Rodolfo Giometti <giometti@...eenne.com>
Cc: linux-kernel@...r.kernel.org,
 Greg Kroah-Hartman <gregkh@...uxfoundation.org>, linux-doc@...r.kernel.org
Subject: Re: [PATCH] Documentation: sysfs-pps: Fix `Description:`s

Hi,

On 2025. 08. 15. 16:09, Rodolfo Giometti wrote:
> On 15/08/25 15:58, Bence Csókás wrote:
>> It is unnecessary to duplicate `What:` content in the description. It
>> makes it harder to both read and maintain.
>>
>> Also, the uapi header no longer lives at `linux/include/linux/pps.h`.
>>
>> Signed-off-by: Bence Csókás <csokas.bence@...lan.hu>
> 
> Acked-by: Rodolfo Giometti <giometti@...eenne.com>

Cc'ing the linux-doc team.

Even though, according to MAINTAINERS, 
Documentation/ABI/testing/sysfs-pps* belongs to the LinuxPPS tree, after 
2 months, I'm starting to wonder if I should have submitted it through 
linux-doc instead.

>> ---
>>   Documentation/ABI/testing/sysfs-pps     | 29 
>> ++++++++++++-----------------
>>   Documentation/ABI/testing/sysfs-pps-gen |  2 +-
>>   2 files changed, 13 insertions(+), 18 deletions(-)
>>
>> diff --git a/Documentation/ABI/testing/sysfs-pps 
>> b/Documentation/ABI/testing/sysfs-pps
>> index 
>> 25028c7bc37d8e50a2d4b53d954a2a0628c4a582..b8034ead5ae530c99fcfd280f295057823a3d613 100644
>> --- a/Documentation/ABI/testing/sysfs-pps
>> +++ b/Documentation/ABI/testing/sysfs-pps
>> @@ -10,16 +10,16 @@ What:        /sys/class/pps/ppsX/
>>   Date:        February 2008
>>   Contact:    Rodolfo Giometti <giometti@...ux.it>
>>   Description:
>> -        The /sys/class/pps/ppsX/ directory is related to X-th
>> -        PPS source into the system. Each directory will
>> -        contain files to manage and control its PPS source.
>> +        This directory represents the X-th PPS source in the system.
>> +        Each directory will contain files to manage and control its
>> +        PPS source.
>>   What:        /sys/class/pps/ppsX/assert
>>   Date:        February 2008
>>   Contact:    Rodolfo Giometti <giometti@...ux.it>
>>   Description:
>> -        The /sys/class/pps/ppsX/assert file reports the assert events
>> -        and the assert sequence number of the X-th source in the form:
>> +        This file reports the assert events and the assert sequence
>> +        number in the form:
>>               <secs>.<nsec>#<sequence>
>> @@ -30,8 +30,8 @@ What:        /sys/class/pps/ppsX/clear
>>   Date:        February 2008
>>   Contact:    Rodolfo Giometti <giometti@...ux.it>
>>   Description:
>> -        The /sys/class/pps/ppsX/clear file reports the clear events
>> -        and the clear sequence number of the X-th source in the form:
>> +        This file reports the clear events and the clear sequence
>> +        number in the form:
>>               <secs>.<nsec>#<sequence>
>> @@ -42,32 +42,27 @@ What:        /sys/class/pps/ppsX/mode
>>   Date:        February 2008
>>   Contact:    Rodolfo Giometti <giometti@...ux.it>
>>   Description:
>> -        The /sys/class/pps/ppsX/mode file reports the functioning
>> -        mode of the X-th source in hexadecimal encoding.
>> +        This file reports the mode bits in hexadecimal encoding.
>> -        Please, refer to linux/include/linux/pps.h for further
>> -        info.
>> +        Please refer to <linux/pps.h> for further info.
>>   What:        /sys/class/pps/ppsX/echo
>>   Date:        February 2008
>>   Contact:    Rodolfo Giometti <giometti@...ux.it>
>>   Description:
>> -        The /sys/class/pps/ppsX/echo file reports if the X-th does
>> -        or does not support an "echo" function.
>> +        Whether this source supports an "echo" function.
>>   What:        /sys/class/pps/ppsX/name
>>   Date:        February 2008
>>   Contact:    Rodolfo Giometti <giometti@...ux.it>
>>   Description:
>> -        The /sys/class/pps/ppsX/name file reports the name of the
>> -        X-th source.
>> +        The name of the PPS source.
>>   What:        /sys/class/pps/ppsX/path
>>   Date:        February 2008
>>   Contact:    Rodolfo Giometti <giometti@...ux.it>
>>   Description:
>> -        The /sys/class/pps/ppsX/path file reports the path name of
>> -        the device connected with the X-th source.
>> +        The path name of the device connected to this source.
>>           If the source is not connected with any device the content
>>           of this file is empty.
>> diff --git a/Documentation/ABI/testing/sysfs-pps-gen 
>> b/Documentation/ABI/testing/sysfs-pps-gen
>> index 
>> 2519207b88fdffdc404238409cb03d0112ce1958..c36bac37a883f1d702ff97e63603d4df7e24de83 100644
>> --- a/Documentation/ABI/testing/sysfs-pps-gen
>> +++ b/Documentation/ABI/testing/sysfs-pps-gen
>> @@ -12,7 +12,7 @@ Date:        February 2025
>>   KernelVersion:  6.13
>>   Contact:    Rodolfo Giometti <giometti@...eenne.com>
>>   Description:
>> -        The /sys/class/pps-gen/pps-genX/ directory is related to X-th
>> +        This directory represents the X-th
>>           PPS generator in the system. Each directory contain files to
>>           manage and control its PPS generator.
>>
>> ---
>> base-commit: 88250d40ed59d2b3c2dff788e9065caa7eb4dba0
>> change-id: 20250815-b4-sysfs-pps-doc-270e54da51b4
>>
>> Best regards,
> 
>