linux-kernel - Re: [RFC 04/11] Documentation/hwmon: Revise hwmon kernel API reference

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <512351f8-e571-620a-1b2b-54989c079803@roeck-us.net>
Date:   Sat, 6 May 2023 06:52:09 -0700
From:   Guenter Roeck <linux@...ck-us.net>
To:     James Seo <james@...iv.tech>, Jean Delvare <jdelvare@...e.com>,
        Jonathan Corbet <corbet@....net>
Cc:     linux-hwmon@...r.kernel.org, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: Re: [RFC 04/11] Documentation/hwmon: Revise hwmon kernel API
 reference

On 5/4/23 00:57, James Seo wrote:
> Reorganize content into coherent sections.
> Use kerneldocs to document functions and data structures when
> possible and add more details on using various API facilities.
> Fix minor issues (typos, grammar, etc.) and add markup.
> 
> Signed-off-by: James Seo <james@...iv.tech>
> ---
>   Documentation/hwmon/hwmon-kernel-api.rst | 740 ++++++++++++-----------
>   1 file changed, 384 insertions(+), 356 deletions(-)
> 
> diff --git a/Documentation/hwmon/hwmon-kernel-api.rst b/Documentation/hwmon/hwmon-kernel-api.rst
> index c2d1e0299d8d..cf084e040522 100644
> --- a/Documentation/hwmon/hwmon-kernel-api.rst
> +++ b/Documentation/hwmon/hwmon-kernel-api.rst
> @@ -1,374 +1,402 @@
> +========================================
>   The Linux Hardware Monitoring kernel API
>   ========================================
>   
>   Guenter Roeck
>   
> +.. contents::
> +
>   Introduction
> -------------
> +============
>   
>   This document describes the API that can be used by hardware monitoring
>   drivers that want to use the hardware monitoring framework.
>   
> -This document does not describe what a hardware monitoring (hwmon) Driver or
> -Device is. It also does not describe the API which can be used by user space
> -to communicate with a hardware monitoring device. If you want to know this
> -then please read the following file: Documentation/hwmon/sysfs-interface.rst.
> +This document does not describe what a hardware monitoring (``hwmon``) driver
> +or device is, nor does it describe the API for communicating with a hardware
> +monitoring device from userspace. For more information on these topics,
> +please read Documentation/hwmon/sysfs-interface.rst.
>   

There is a lot of nnecessary churn in your patches, where you reformat entire
paragrahps just to add a few "``". This makes it almost impossible to identify
the actual changes. For me it means that the review burden is so much that I'll
probably never get to actually review those changes.

Please split the changes into subjects, following the "one logical change per
patch" rule, and please refrain from changing entire paragraphs when adding
markups. Also, a reference to the markup rules explaining if and when markups
are warranted would be nice. For example, I have no idea why "hwmon" would
warrant a markup.

Guenter