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;
Sender: Guenter Roeck <groeck7@gmail.com>
Message-ID: <512351f8-e571-620a-1b2b-54989c079803@roeck-us.net>
Date:   Sat, 6 May 2023 06:52:09 -0700
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.10.0
Content-Language: en-US
To:     James Seo <james@equiv.tech>, Jean Delvare <jdelvare@suse.com>,
        Jonathan Corbet <corbet@lwn.net>
Cc:     linux-hwmon@vger.kernel.org, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
References: <20230504075752.1320967-1-james@equiv.tech>
 <20230504075752.1320967-5-james@equiv.tech>
From:   Guenter Roeck <linux@roeck-us.net>
Subject: Re: [RFC 04/11] Documentation/hwmon: Revise hwmon kernel API
 reference
In-Reply-To: <20230504075752.1320967-5-james@equiv.tech>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Precedence: bulk

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@equiv.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