Re: [PATCHv2 09/12] staging: ti-soc-thermal: fix several kernel-doc warnings and error
On Tue, Mar 19, 2013 at 10:54:25AM -0400, Eduardo Valentin wrote: This patch updates the documentation to remove all warnings and errors reported by scripts/kernel-doc. Most are missing arguments due to wrong format. Cc: Nishanth Menon n...@ti.com Signed-off-by: Eduardo Valentin eduardo.valen...@ti.com In the future, don't put empty lines between the Cc: and signed-off-by: lines please, I had to hand-edit all of these to fix that... greg k-h -- To unsubscribe from this list: send the line unsubscribe linux-omap in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCHv2 09/12] staging: ti-soc-thermal: fix several kernel-doc warnings and error
On 25-03-2013 14:22, Greg KH wrote: On Tue, Mar 19, 2013 at 10:54:25AM -0400, Eduardo Valentin wrote: This patch updates the documentation to remove all warnings and errors reported by scripts/kernel-doc. Most are missing arguments due to wrong format. Cc: Nishanth Menon n...@ti.com Signed-off-by: Eduardo Valentin eduardo.valen...@ti.com In the future, don't put empty lines between the Cc: and signed-off-by: lines please, I had to hand-edit all of these to fix that... Ok. Sure.. My bad.. greg k-h -- To unsubscribe from this list: send the line unsubscribe linux-omap in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCHv2 09/12] staging: ti-soc-thermal: fix several kernel-doc warnings and error
Hello Nishanth,
On 19-03-2013 15:22, Nishanth Menon wrote:
On 10:54-20130319, Eduardo Valentin wrote:
cut
* @adc_start_val: ADC conversion table starting value
You may still want to fix warnings generated by:
./scripts/kernel-doc -v drivers/staging/ti-soc-thermal/ti-bandgap.c/dev/null
For example - the following changes are required for proper error return
documentation (following diff is just an hint):
Although I think the above is a good thing to be done, I don't think it
is considered mandatory, and for this reason, I don't believe the above
should block this patch. Basically because, after this patch, at least
kernel-doc runs successfully.
Besides, there is very few evidence that ppl out there care much about
-v. A quick grep+awk would inform you this. If you consider the
population of C files (around 35.4K files) inside the tree (simple find
* | grep .*\\.[c,h]$ in your tree), only around 12.0% has structured
comments. Out of the files that have structured comments, only about
11.0% has 0 warnings (including 0 warnings with -v), that's something
like ~500 files. A considerable amount don't care about -v (34% out of
the files with structured comments). Actually most of them don't care
about warnings (89% out of the files with structured comments) at all. :-)
That said, I am going to send a separate patch to fix the -v later on.
Including your chunks below.
Thanks for reviewing.
diff --git a/drivers/staging/ti-soc-thermal/ti-bandgap.c
b/drivers/staging/ti-soc-thermal/ti-bandgap.c
index d479e50..0adae05 100644
--- a/drivers/staging/ti-soc-thermal/ti-bandgap.c
+++ b/drivers/staging/ti-soc-thermal/ti-bandgap.c
@@ -50,7 +50,7 @@
* @reg: desired register (offset) to be read
*
* Helper function to read bandgap registers. It uses the io remapped area.
- * Returns the register value.
+ * Return: the register value.
*/
static u32 ti_bandgap_readl(struct ti_bandgap *bgp, u32 reg)
{
@@ -97,6 +97,8 @@ do {
\
*
* Used to power on/off a bandgap device instance. Only used on those
* that features tempsoff bit.
+ *
+ * Return: 0
*/
static int ti_bandgap_power(struct ti_bandgap *bgp, bool on)
{
@@ -122,6 +124,8 @@ exit:
* This function is desired because, depending on bandgap device version,
* it might be needed to freeze the bandgap state machine, before fetching
* the register value.
+ *
+ * Return: temperature in ...
*/
static u32 ti_bandgap_read_temp(struct ti_bandgap *bgp, int id)
{
@@ -162,6 +166,8 @@ static u32 ti_bandgap_read_temp(struct ti_bandgap *bgp, int
id)
* conditions and acts accordingly. In case there are events pending,
* it will reset the event mask to wait for the opposite event (next event).
* Every time there is a new event, it will be reported to thermal layer.
+ *
+ * Return: IRQ_HANDLED
*/
static irqreturn_t ti_bandgap_talert_irq_handler(int irq, void *data)
{
@@ -222,6 +228,8 @@ static irqreturn_t ti_bandgap_talert_irq_handler(int irq,
void *data)
* This is the Tshut handler. Use it only if bandgap device features
* HAS(TSHUT). If any sensor fires the Tshut signal, we simply shutdown
* the system.
+ *
+ * Return: IRQ_HANDLED
*/
static irqreturn_t ti_bandgap_tshut_irq_handler(int irq, void *data)
{
@@ -244,6 +252,8 @@ static irqreturn_t ti_bandgap_tshut_irq_handler(int irq,
void *data)
* Simple conversion from ADC representation to mCelsius. In case the ADC
value
* is out of the ADC conv table range, it returns -ERANGE, 0 on success.
* The conversion table is indexed by the ADC values.
+ *
+ * Return: 0 if converstion was successful, else -ERANGE if out of range
*/
static
int ti_bandgap_adc_to_mcelsius(struct ti_bandgap *bgp, int adc_val, int *t)
@@ -272,6 +282,8 @@ exit:
* Simple conversion from mCelsius to ADC values. In case the temp value
* is out of the ADC conv table range, it returns -ERANGE, 0 on success.
* The conversion table is indexed by the ADC values.
+ *
+ * Return: 0 if converstion was successful, else -ERANGE if out of range
*/
static
int ti_bandgap_mcelsius_to_adc(struct ti_bandgap *bgp, long temp, int *adc)
@@ -311,7 +323,8 @@ exit:
* @sum: address where to write the resulting temperature (in ADC scale)
*
* Adds an hysteresis value (in mCelsius) to a ADC temperature value.
- * Returns 0 on success, -ERANGE otherwise.
+ *
+ * Return: 0 on success, -ERANGE otherwise.
*/
static
int ti_bandgap_add_hyst(struct ti_bandgap *bgp, int adc_val, int hyst_val,
@@ -384,6 +397,8 @@ static void ti_bandgap_unmask_interrupts(struct ti_bandgap
*bgp, int id,
* It checks the resulting t_hot and t_cold values, based on the new passed
@val
* and configures the thresholds so that t_hot is always greater than t_cold.
* Call this function only if bandgap features HAS(TALERT).
+ *
+ * Return: 0 if no error, else corresponding error
*/
static int
Re: [PATCHv2 09/12] staging: ti-soc-thermal: fix several kernel-doc warnings and error
On Wed, Mar 20, 2013 at 6:56 AM, Eduardo Valentin eduardo.valen...@ti.com wrote: On 19-03-2013 15:22, Nishanth Menon wrote: On 10:54-20130319, Eduardo Valentin wrote: [..] You may still want to fix warnings generated by: ./scripts/kernel-doc -v drivers/staging/ti-soc-thermal/ti-bandgap.c/dev/null For example - the following changes are required for proper error return documentation (following diff is just an hint): Although I think the above is a good thing to be done, I don't think it is considered mandatory, and for this reason, I don't believe the above should block this patch. Basically because, after this patch, at least kernel-doc runs successfully. Besides, there is very few evidence that ppl out there care much about -v. A quick grep+awk would inform you this. If you consider the population of C files (around 35.4K files) inside the tree (simple find * | grep .*\\.[c,h]$ in your tree), only around 12.0% has structured comments. Out of the files that have structured comments, only about 11.0% has 0 warnings (including 0 warnings with -v), that's something like ~500 files. A considerable amount don't care about -v (34% out of the files with structured comments). Actually most of them don't care about warnings (89% out of the files with structured comments) at all. :-) Yep, commit 4092bac7 That said, I am going to send a separate patch to fix the -v later on. Including your chunks below. Thanks. Regards, Nishanth Menon -- To unsubscribe from this list: send the line unsubscribe linux-omap in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCHv2 09/12] staging: ti-soc-thermal: fix several kernel-doc warnings and error
This patch updates the documentation to remove all warnings and errors reported by scripts/kernel-doc. Most are missing arguments due to wrong format. Cc: Nishanth Menon n...@ti.com Signed-off-by: Eduardo Valentin eduardo.valen...@ti.com --- drivers/staging/ti-soc-thermal/ti-bandgap.c | 56 +- drivers/staging/ti-soc-thermal/ti-bandgap.h |8 ++-- 2 files changed, 32 insertions(+), 32 deletions(-) diff --git a/drivers/staging/ti-soc-thermal/ti-bandgap.c b/drivers/staging/ti-soc-thermal/ti-bandgap.c index 7d67f72..a9d6d2a 100644 --- a/drivers/staging/ti-soc-thermal/ti-bandgap.c +++ b/drivers/staging/ti-soc-thermal/ti-bandgap.c @@ -340,6 +340,7 @@ exit: /** * ti_bandgap_unmask_interrupts() - unmasks the events of thot tcold * @bgp: struct ti_bandgap pointer + * @id: bandgap sensor id * @t_hot: hot temperature value to trigger alert signal * @t_cold: cold temperature value to trigger alert signal * @@ -570,9 +571,9 @@ exit: /** * ti_bandgap_read_thot() - reads sensor current thot - * @bgp - pointer to bandgap instance - * @id - sensor id - * @thot - resulting current thot value + * @bgp: pointer to bandgap instance + * @id: sensor id + * @thot: resulting current thot value * * returns 0 on success or the proper error code */ @@ -583,9 +584,9 @@ int ti_bandgap_read_thot(struct ti_bandgap *bgp, int id, int *thot) /** * ti_bandgap_write_thot() - sets sensor current thot - * @bgp - pointer to bandgap instance - * @id - sensor id - * @val - desired thot value + * @bgp: pointer to bandgap instance + * @id: sensor id + * @val: desired thot value * * returns 0 on success or the proper error code */ @@ -596,9 +597,9 @@ int ti_bandgap_write_thot(struct ti_bandgap *bgp, int id, int val) /** * ti_bandgap_read_tcold() - reads sensor current tcold - * @bgp - pointer to bandgap instance - * @id - sensor id - * @tcold - resulting current tcold value + * @bgp: pointer to bandgap instance + * @id: sensor id + * @tcold: resulting current tcold value * * returns 0 on success or the proper error code */ @@ -609,9 +610,9 @@ int ti_bandgap_read_tcold(struct ti_bandgap *bgp, int id, int *tcold) /** * ti_bandgap_write_tcold() - sets the sensor tcold - * @bgp - pointer to bandgap instance - * @id - sensor id - * @val - desired tcold value + * @bgp: pointer to bandgap instance + * @id: sensor id + * @val: desired tcold value * * returns 0 on success or the proper error code */ @@ -622,9 +623,9 @@ int ti_bandgap_write_tcold(struct ti_bandgap *bgp, int id, int val) /** * ti_bandgap_read_update_interval() - read the sensor update interval - * @bgp - pointer to bandgap instance - * @id - sensor id - * @interval - resulting update interval in miliseconds + * @bgp: pointer to bandgap instance + * @id: sensor id + * @interval: resulting update interval in miliseconds * * returns 0 on success or the proper error code */ @@ -654,9 +655,9 @@ int ti_bandgap_read_update_interval(struct ti_bandgap *bgp, int id, /** * ti_bandgap_write_update_interval() - set the update interval - * @bgp - pointer to bandgap instance - * @id - sensor id - * @interval - desired update interval in miliseconds + * @bgp: pointer to bandgap instance + * @id: sensor id + * @interval: desired update interval in miliseconds * * returns 0 on success or the proper error code */ @@ -680,9 +681,9 @@ int ti_bandgap_write_update_interval(struct ti_bandgap *bgp, /** * ti_bandgap_read_temperature() - report current temperature - * @bgp - pointer to bandgap instance - * @id - sensor id - * @temperature - resulting temperature + * @bgp: pointer to bandgap instance + * @id: sensor id + * @temperature: resulting temperature * * returns 0 on success or the proper error code */ @@ -712,9 +713,9 @@ int ti_bandgap_read_temperature(struct ti_bandgap *bgp, int id, /** * ti_bandgap_set_sensor_data() - helper function to store thermal * framework related data. - * @bgp - pointer to bandgap instance - * @id - sensor id - * @data - thermal framework related data to be stored + * @bgp: pointer to bandgap instance + * @id: sensor id + * @data: thermal framework related data to be stored * * returns 0 on success or the proper error code */ @@ -732,8 +733,8 @@ int ti_bandgap_set_sensor_data(struct ti_bandgap *bgp, int id, void *data) /** * ti_bandgap_get_sensor_data() - helper function to get thermal * framework related data. - * @bgp - pointer to bandgap instance - * @id - sensor id + * @bgp: pointer to bandgap instance + * @id: sensor id * * returns data stored by set function with sensor id on success or NULL */ @@ -875,16 +876,15 @@ static int ti_bandgap_talert_init(struct ti_bandgap *bgp, return 0; } +static const struct of_device_id of_ti_bandgap_match[]; /** * ti_bandgap_build() - parse DT and setup a struct ti_bandgap - * @bgp: pointer to struct ti_bandgap * @pdev: pointer to device struct platform_device * * Used to read
Re: [PATCHv2 09/12] staging: ti-soc-thermal: fix several kernel-doc warnings and error
On 10:54-20130319, Eduardo Valentin wrote: This patch updates the documentation to remove all warnings and errors reported by scripts/kernel-doc. Most are missing arguments due to wrong format. Cc: Nishanth Menon n...@ti.com Signed-off-by: Eduardo Valentin eduardo.valen...@ti.com --- drivers/staging/ti-soc-thermal/ti-bandgap.c | 56 +- drivers/staging/ti-soc-thermal/ti-bandgap.h |8 ++-- 2 files changed, 32 insertions(+), 32 deletions(-) diff --git a/drivers/staging/ti-soc-thermal/ti-bandgap.c b/drivers/staging/ti-soc-thermal/ti-bandgap.c index 7d67f72..a9d6d2a 100644 --- a/drivers/staging/ti-soc-thermal/ti-bandgap.c +++ b/drivers/staging/ti-soc-thermal/ti-bandgap.c @@ -340,6 +340,7 @@ exit: /** * ti_bandgap_unmask_interrupts() - unmasks the events of thot tcold * @bgp: struct ti_bandgap pointer + * @id: bandgap sensor id * @t_hot: hot temperature value to trigger alert signal * @t_cold: cold temperature value to trigger alert signal * @@ -570,9 +571,9 @@ exit: /** * ti_bandgap_read_thot() - reads sensor current thot - * @bgp - pointer to bandgap instance - * @id - sensor id - * @thot - resulting current thot value + * @bgp: pointer to bandgap instance + * @id: sensor id + * @thot: resulting current thot value * * returns 0 on success or the proper error code */ @@ -583,9 +584,9 @@ int ti_bandgap_read_thot(struct ti_bandgap *bgp, int id, int *thot) /** * ti_bandgap_write_thot() - sets sensor current thot - * @bgp - pointer to bandgap instance - * @id - sensor id - * @val - desired thot value + * @bgp: pointer to bandgap instance + * @id: sensor id + * @val: desired thot value * * returns 0 on success or the proper error code */ @@ -596,9 +597,9 @@ int ti_bandgap_write_thot(struct ti_bandgap *bgp, int id, int val) /** * ti_bandgap_read_tcold() - reads sensor current tcold - * @bgp - pointer to bandgap instance - * @id - sensor id - * @tcold - resulting current tcold value + * @bgp: pointer to bandgap instance + * @id: sensor id + * @tcold: resulting current tcold value * * returns 0 on success or the proper error code */ @@ -609,9 +610,9 @@ int ti_bandgap_read_tcold(struct ti_bandgap *bgp, int id, int *tcold) /** * ti_bandgap_write_tcold() - sets the sensor tcold - * @bgp - pointer to bandgap instance - * @id - sensor id - * @val - desired tcold value + * @bgp: pointer to bandgap instance + * @id: sensor id + * @val: desired tcold value * * returns 0 on success or the proper error code */ @@ -622,9 +623,9 @@ int ti_bandgap_write_tcold(struct ti_bandgap *bgp, int id, int val) /** * ti_bandgap_read_update_interval() - read the sensor update interval - * @bgp - pointer to bandgap instance - * @id - sensor id - * @interval - resulting update interval in miliseconds + * @bgp: pointer to bandgap instance + * @id: sensor id + * @interval: resulting update interval in miliseconds * * returns 0 on success or the proper error code */ @@ -654,9 +655,9 @@ int ti_bandgap_read_update_interval(struct ti_bandgap *bgp, int id, /** * ti_bandgap_write_update_interval() - set the update interval - * @bgp - pointer to bandgap instance - * @id - sensor id - * @interval - desired update interval in miliseconds + * @bgp: pointer to bandgap instance + * @id: sensor id + * @interval: desired update interval in miliseconds * * returns 0 on success or the proper error code */ @@ -680,9 +681,9 @@ int ti_bandgap_write_update_interval(struct ti_bandgap *bgp, /** * ti_bandgap_read_temperature() - report current temperature - * @bgp - pointer to bandgap instance - * @id - sensor id - * @temperature - resulting temperature + * @bgp: pointer to bandgap instance + * @id: sensor id + * @temperature: resulting temperature * * returns 0 on success or the proper error code */ @@ -712,9 +713,9 @@ int ti_bandgap_read_temperature(struct ti_bandgap *bgp, int id, /** * ti_bandgap_set_sensor_data() - helper function to store thermal * framework related data. - * @bgp - pointer to bandgap instance - * @id - sensor id - * @data - thermal framework related data to be stored + * @bgp: pointer to bandgap instance + * @id: sensor id + * @data: thermal framework related data to be stored * * returns 0 on success or the proper error code */ @@ -732,8 +733,8 @@ int ti_bandgap_set_sensor_data(struct ti_bandgap *bgp, int id, void *data) /** * ti_bandgap_get_sensor_data() - helper function to get thermal * framework related data. - * @bgp - pointer to bandgap instance - * @id - sensor id + * @bgp: pointer to bandgap instance + * @id: sensor id * * returns data stored by set function with sensor id on success or NULL */ @@ -875,16 +876,15 @@ static int ti_bandgap_talert_init(struct ti_bandgap *bgp, return 0; } +static const struct of_device_id
