From: Javi Merino <javi.merino@arm.com>
To: Andy Champ <andycham@amazon.com>
Cc: edubezval@gmail.com, corbet@lwn.net, durgadoss.r@intel.com,
leo.yan@linaro.org, kapileshwar.singh@arm.com, wni@nvidia.com,
linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH] Syntactic and factual errors in the API document
Date: Tue, 22 Mar 2016 14:35:50 +0000 [thread overview]
Message-ID: <20160322143529.GB3087@e104805> (raw)
In-Reply-To: <1458650245-24303-1-git-send-email-andycham@amazon.com>
Hi Andy,
Thanks for improving the documentation! One minor nit below. Other
than that, you can add my reviewed-by.
On Tue, Mar 22, 2016 at 12:37:25PM +0000, Andy Champ wrote:
> There are several places where the English in the document is syntactically
> invalid, or unclear. There are also one or two factual errors.
>
> ---
> Documentation/thermal/sysfs-api.txt | 44 ++++++++++++++++++-------------------
> 1 file changed, 22 insertions(+), 22 deletions(-)
>
> diff --git a/Documentation/thermal/sysfs-api.txt b/Documentation/thermal/sysfs-api.txt
> index 8c745c8..5bc73ef 100644
> --- a/Documentation/thermal/sysfs-api.txt
> +++ b/Documentation/thermal/sysfs-api.txt
> @@ -69,8 +69,8 @@ temperature) and throttle appropriate devices.
> 1.1.2 void thermal_zone_device_unregister(struct thermal_zone_device *tz)
>
> This interface function removes the thermal zone device.
> - It deletes the corresponding entry form /sys/class/thermal folder and
> - unbind all the thermal cooling devices it uses.
> + It deletes the corresponding entry from /sys/class/thermal folder and
> + unbinds all the thermal cooling devices it uses.
>
> 1.2 thermal cooling device interface
> 1.2.1 struct thermal_cooling_device *thermal_cooling_device_register(char *name,
> @@ -78,32 +78,32 @@ temperature) and throttle appropriate devices.
>
> This interface function adds a new thermal cooling device (fan/processor/...)
> to /sys/class/thermal/ folder as cooling_device[0-*]. It tries to bind itself
> - to all the thermal zone devices register at the same time.
> + to all the thermal zone devices registered at the same time.
> name: the cooling device name.
> devdata: device private data.
> ops: thermal cooling devices call-backs.
> .get_max_state: get the Maximum throttle state of the cooling device.
> - .get_cur_state: get the Current throttle state of the cooling device.
> + .get_cur_state: get the Currently requested throttle state of the cooling device.
Not sure about this one. It's good that it uses the same language as
set_cur_state. What's the problem with "Current throttle state"?
> .set_cur_state: set the Current throttle state of the cooling device.
>
> 1.2.2 void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)
>
> - This interface function remove the thermal cooling device.
> - It deletes the corresponding entry form /sys/class/thermal folder and
> - unbind itself from all the thermal zone devices using it.
> + This interface function removes the thermal cooling device.
> + It deletes the corresponding entry from /sys/class/thermal folder and
> + unbinds itself from all the thermal zone devices using it.
>
> 1.3 interface for binding a thermal zone device with a thermal cooling device
> 1.3.1 int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz,
> int trip, struct thermal_cooling_device *cdev,
> unsigned long upper, unsigned long lower, unsigned int weight);
>
> - This interface function bind a thermal cooling device to the certain trip
> + This interface function binds a thermal cooling device to a particular trip
> point of a thermal zone device.
> This function is usually called in the thermal zone device .bind callback.
> tz: the thermal zone device
> cdev: thermal cooling device
> - trip: indicates which trip point the cooling devices is associated with
> - in this thermal zone.
> + trip: indicates which trip point in this thermal zone the cooling device
> + is associated with.
> upper:the Maximum cooling state for this trip point.
> THERMAL_NO_LIMIT means no upper limit,
> and the cooling device can be in max_state.
> @@ -116,13 +116,13 @@ temperature) and throttle appropriate devices.
> 1.3.2 int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz,
> int trip, struct thermal_cooling_device *cdev);
>
> - This interface function unbind a thermal cooling device from the certain
> + This interface function unbinds a thermal cooling device from a particular
> trip point of a thermal zone device. This function is usually called in
> the thermal zone device .unbind callback.
> tz: the thermal zone device
> cdev: thermal cooling device
> - trip: indicates which trip point the cooling devices is associated with
> - in this thermal zone.
> + trip: indicates which trip point in this thermal zone the cooling device
> + is associated with.
>
> 1.4 Thermal Zone Parameters
> 1.4.1 struct thermal_bind_params
> @@ -142,13 +142,13 @@ temperature) and throttle appropriate devices.
> this thermal zone and cdev, for a particular trip point.
> If nth bit is set, then the cdev and thermal zone are bound
> for trip point n.
> - .limits: This is an array of cooling state limits. Must have exactly
> - 2 * thermal_zone.number_of_trip_points. It is an array consisting
> - of tuples <lower-state upper-state> of state limits. Each trip
> - will be associated with one state limit tuple when binding.
> - A NULL pointer means <THERMAL_NO_LIMITS THERMAL_NO_LIMITS>
> - on all trips. These limits are used when binding a cdev to a
> - trip point.
> + .binding_limits: This is an array of cooling state limits. Must have
> + exactly 2 * thermal_zone.number_of_trip_points. It is an
> + array consisting of tuples <lower-state upper-state> of
> + state limits. Each trip will be associated with one state
> + limit tuple when binding. A NULL pointer means
> + <THERMAL_NO_LIMITS THERMAL_NO_LIMITS> on all trips.
> + These limits are used when binding a cdev to a trip point.
> .match: This call back returns success(0) if the 'tz and cdev' need to
> be bound, as per platform data.
> 1.4.2 struct thermal_zone_params
> @@ -283,8 +283,8 @@ cdev[0-*]
> RO, Optional
>
> cdev[0-*]_trip_point
> - The trip point with which cdev[0-*] is associated in this thermal
> - zone; -1 means the cooling device is not associated with any trip
> + The trip point in this thermal zone which cdev[0-*] is associated
> + with; -1 means the cooling device is not associated with any trip
> point.
> RO, Optional
>
next prev parent reply other threads:[~2016-03-22 14:36 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-03-22 12:37 [PATCH] Syntactic and factual errors in the API document Andy Champ
2016-03-22 13:24 ` R, Durgadoss
2016-03-22 14:35 ` Javi Merino [this message]
2016-03-22 14:53 ` Champ, Andy
2016-03-22 16:00 ` Eduardo Valentin
2016-03-28 13:41 ` Eduardo Valentin
2016-03-31 6:43 ` Jonathan Corbet
2016-03-31 8:32 ` Champ, Andy
2016-03-31 8:58 ` Javi Merino
2016-04-01 12:43 ` Champ, Andy
2016-04-01 2:35 ` Eduardo Valentin
2016-04-01 13:42 ` Jonathan Corbet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20160322143529.GB3087@e104805 \
--to=javi.merino@arm.com \
--cc=andycham@amazon.com \
--cc=corbet@lwn.net \
--cc=durgadoss.r@intel.com \
--cc=edubezval@gmail.com \
--cc=kapileshwar.singh@arm.com \
--cc=leo.yan@linaro.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=wni@nvidia.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).