regulator: kerneldoc cleanups
Subsystems (2)
cover regulator: kerneldoc cleanups
This patch series cleans up the kerneldoc for the regulator API and adds a brief DocBook manual for it, based heavily on the existing plain text documentation but much less complete. I'm not sure that the manual itself is actually worthwhile, the main benefit from it is the generated documentation rather than the text in the manual itself - I did the work to help with generating the earlier fixes.
It may be worth considering the first four patches for 2.6.29 as fixes, though it's questionable.
The following changes since commit b6fe1c783638104350147877f5823d8faa68f6a2:
David Brownell (1):
regulator: init/link earlier
are available in the git repository at:
git://git.kernel.org/pub/scm/linux/kernel/git/broonie/regulator-2.6.git topic/doc
Mark Brown (5):
regulator: Remove extraneous kerneldoc annotations
regulator: Clean up kerneldoc warnings
regulator: Add missing kerneldoc
regulator: Fix some kerneldoc rendering issues
regulator: Add basic DocBook manual
Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/regulator.tmpl | 304 ++++++++++++++++++++++++++++++++++ drivers/regulator/core.c | 57 ++++--- include/linux/regulator/consumer.h | 8 +- include/linux/regulator/driver.h | 40 +++++- include/linux/regulator/machine.h | 41 +++++ 6 files changed, 420 insertions(+), 32 deletions(-) create mode 100644 Documentation/DocBook/regulator.tmpl
PATCH 1/5 regulator: Remove extraneous kerneldoc annotations
Some of the internal structures have no kerneldoc but the ** at the start of the comment marking them for documentation. Remove the annotation until some is added.
--- drivers/regulator/core.c | 4 ++-- 1 files changed, 2 insertions(+), 2 deletions(-)
drivers/regulator/core.c +2 -2
@@ -29,7 +29,7 @@ static DEFINE_MUTEX(regulator_list_mutex);static LIST_HEAD (regulator_list);static LIST_HEAD (regulator_map_list); -/** +/* * struct regulator_dev * * Voltage / Current regulator class device. One for each regulator.
@@ -56,7 +56,7 @@ struct regulator_dev {void *reg_data;/* regulator_dev data */ }; -/** +/* * struct regulator_map * * Used to provide symbolic supply names to devices.
Signature · 1 line
1.5.6.3
PATCH 2/5 regulator: Clean up kerneldoc warnings
Remove kerneldoc warnings that don't relate to missing documentation, mostly by renaming parameters in the documentation to match their actual names.
--- drivers/regulator/core.c | 44 ++++++++++++++++++------------------ include/linux/regulator/consumer.h | 8 +++--- 2 files changed, 26 insertions(+), 26 deletions(-)
drivers/regulator/core.c +22 -22
@@ -655,7 +655,7 @@ static void print_constraints(struct regulator_dev *rdev)/** * set_machine_constraints - sets regulator constraints -* @regulator: regulator source +* @rdev: regulator source * * Allows platform initialisation code to define and constrain * regulator circuits e.g. valid voltage/current ranges, etc. NOTE:
@@ -730,8 +730,8 @@ out:/** * set_supply - set regulator supply regulator -* @regulator: regulator name -* @supply: supply regulator name +* @rdev: regulator name +* @supply_rdev: supply regulator name * * Called by platform initialisation code to set the supply regulator for this * regulator. This ensures that a regulators supply will also be enabled by the
@@ -758,9 +758,9 @@ out:/** * set_consumer_device_supply: Bind a regulator to a symbolic supply -* @regulator: regulator source -* @dev: device the supply applies to -* @supply: symbolic name for supply +* @rdev: regulator source +* @consumer_dev: device the supply applies to +* @supply: symbolic name for supply * * Allows platform initialisation code to map physical regulator * sources to symbolic names for supplies for use by devices. Devices
@@ -1013,9 +1013,8 @@ static int _regulator_enable(struct regulator_dev *rdev)* * Enable the regulator output at the predefined voltage or current value. * NOTE: the output value can be set by other drivers, boot loader or may be -* hardwired in the regulator. -* NOTE: calls to regulator_enable() must be balanced with calls to -* regulator_disable(). +* hardwired in the regulator. Calls to regulator_enable() must be balanced +* with calls to regulator_disable(). */ int regulator_enable (struct regulator *regulator) {
@@ -1074,10 +1073,10 @@ static int _regulator_disable(struct regulator_dev *rdev)* @regulator: regulator source * * Disable the regulator output voltage or current. +* * NOTE: this will only disable the regulator output if no other consumer -* devices have it enabled. -* NOTE: calls to regulator_enable() must be balanced with calls to -* regulator_disable(). +* devices have it enabled. Calls to regulator_enable() must be balanced with +* calls to regulator_disable(). */ int regulator_disable (struct regulator *regulator) {
@@ -1200,7 +1199,7 @@ EXPORT_SYMBOL_GPL(regulator_is_enabled);* * NOTE: If the regulator is shared between several devices then the lowest * request voltage that meets the system constraints will be used. -* NOTE: Regulator system constraints must be set for this regulator before +* Regulator system constraints must be set for this regulator before * calling this function otherwise this call will fail. */ int regulator_set_voltage (struct regulator *regulator,int min_uV,int max_uV)
@@ -1498,7 +1497,7 @@ EXPORT_SYMBOL_GPL(regulator_set_optimum_mode);/** * regulator_register_notifier - register regulator event notifier * @regulator: regulator source -* @notifier_block: notifier block +* @nb: notifier block * * Register notifier block to receive regulator events. */
@@ -1513,7 +1512,7 @@ EXPORT_SYMBOL_GPL(regulator_register_notifier);/** * regulator_unregister_notifier - unregister regulator event notifier * @regulator: regulator source -* @notifier_block: notifier block +* @nb: notifier block * * Unregister regulator event notifier block. */
@@ -1679,9 +1678,9 @@ EXPORT_SYMBOL_GPL(regulator_bulk_free);/** * regulator_notifier_call_chain - call regulator event notifier -* @regulator: regulator source +* @rdev: regulator source * @event: notifier block -* @data: +* @data: callback-specific data. * * Called by regulator drivers to notify clients a regulator event has * occurred. We also notify regulator clients downstream.
@@ -1808,8 +1807,9 @@ static int add_regulator_attributes(struct regulator_dev *rdev)/** * regulator_register - register regulator -* @regulator: regulator source -* @reg_data: private regulator data +* @regulator_desc: regulator to register +* @dev: struct device for the regulator +* @driver_data: private regulator data * * Called by regulator drivers to register a regulator. * Returns 0 on success.
@@ -1916,7 +1916,7 @@ EXPORT_SYMBOL_GPL(regulator_register);/** * regulator_unregister - unregister regulator -* @regulator: regulator source +* @rdev: regulator to unregister * * Called by regulator drivers to unregister a regulator. */
@@ -1971,7 +1971,7 @@ EXPORT_SYMBOL_GPL(regulator_suspend_prepare);/** * rdev_get_drvdata - get rdev regulator driver data -* @regulator: regulator +* @rdev: regulator * * Get rdev regulator driver private data. This call can be used in the * regulator driver context.
@@ -2008,7 +2008,7 @@ EXPORT_SYMBOL_GPL(regulator_set_drvdata);/** * regulator_get_id - get regulator ID -* @regulator: regulator +* @rdev: regulator */ int rdev_get_id (struct regulator_dev *rdev) {
include/linux/regulator/consumer.h +4 -4
@@ -104,10 +104,10 @@ struct regulator;/** * struct regulator_bulk_data - Data used for bulk regulator operations. * -* @supply The name of the supply. Initialised by the user before -* using the bulk regulator APIs. -* @consumer The regulator consumer for the supply. This will be managed -* by the bulk API. +* @supply: The name of the supply. Initialised by the user before +* using the bulk regulator APIs. +* @consumer: The regulator consumer for the supply. This will be managed +* by the bulk API. * * The regulator APIs provide a series of regulator_bulk_() API calls as * a convenience to consumers which require multiple supplies. This
Signature · 1 line
1.5.6.3
PATCH 3/5 regulator: Add missing kerneldoc
This is only the documentation that the kerneldoc system warns about.
--- drivers/regulator/core.c | 1 + include/linux/regulator/driver.h | 40 +++++++++++++++++++++++++++++++++++- include/linux/regulator/machine.h | 41 +++++++++++++++++++++++++++++++++++++ 3 files changed, 81 insertions(+), 1 deletions(-)
drivers/regulator/core.c +1 -0
@@ -656,6 +656,7 @@ static void print_constraints(struct regulator_dev *rdev)/** * set_machine_constraints - sets regulator constraints * @rdev: regulator source +* @constraints: constraints to apply * * Allows platform initialisation code to define and constrain * regulator circuits e.g. valid voltage/current ranges, etc. NOTE:
include/linux/regulator/driver.h +39 -1
@@ -24,7 +24,37 @@ struct regulator_init_data;/** * struct regulator_ops - regulator operations. * -* This struct describes regulator operations. +* This struct describes regulator operations which can be implemented by +* regulator chip drivers. +* +* @enable: Enable the regulator. +* @disable: Disable the regulator. +* @is_enabled: Return 1 if the reguator is enabled, 0 otherwise. +* +* @set_voltage: Set the voltage for the regulator within the range specified. +* The driver should select the voltage closest to min_uV. +* @get_voltage: Return the currently configured voltage for the regulator. +* +* @set_current: Set the current for the regulator within the range specified. +* The driver should select the current closest to min_uA. +* @get_current: Return the currently configured current for the regulator. +* +* @set_current_limit: Configure a limit for a current-limited regulator. +* @get_current_limit: Get the limit for a current-limited regulator. +* +* @set_mode: Set the operating mode for the regulator. +* @get_mode: Get the current operating mode for the regulator. +* @get_optimum_mode: Get the most efficient operating mode for the regulator +* when running with the specified parameters. +* +* @set_suspend_voltage: Set the voltage for the regulator when the system +* is suspended. +* @set_suspend_enable: Mark the regulator as enabled when the system is +* suspended. +* @set_suspend_disable: Mark the regulator as disabled when the system is +* suspended. +* @set_suspend_mode: Set the operating mode for the regulator when the +* system is suspended. */ struct regulator_ops {
@@ -75,6 +105,14 @@ enum regulator_type {/** * struct regulator_desc - Regulator descriptor * +* Each regulator registered with the core is described with a structure of +* this type. +* +* @name: Identifying name for the regulator. +* @id: Numerical identifier for the regulator. +* @ops: Regulator operations table. +* @type: Indicates if the regulator is a voltage or current regulator. +* @owner: Module providing the regulator, used for refcounting. */ struct regulator_desc {const char *name;
include/linux/regulator/machine.h +41 -0
65 lines not on this page · raw message
Signature · 1 line
1.5.6.3
PATCH 4/5 regulator: Fix some kerneldoc rendering issues
There are some minor textual changes in here as well, mostly to enable() and disable() but the primary goal of these changes is to fix misrenderings of the kerneldoc documentation for the regulator API.
--- drivers/regulator/core.c | 18 +++++++++++------- 1 files changed, 11 insertions(+), 7 deletions(-)
drivers/regulator/core.c +11 -7
@@ -1012,10 +1012,12 @@ static int _regulator_enable(struct regulator_dev *rdev)* regulator_enable - enable regulator output * @regulator: regulator source * -* Enable the regulator output at the predefined voltage or current value. +* Request that the regulator be enabled with the regulator output at +* the predefined voltage or current value. Calls to regulator_enable() +* must be balanced with calls to regulator_disable(). +* * NOTE: the output value can be set by other drivers, boot loader or may be -* hardwired in the regulator. Calls to regulator_enable() must be balanced -* with calls to regulator_disable(). +* hardwired in the regulator. */ int regulator_enable (struct regulator *regulator) {
@@ -1073,11 +1075,13 @@ static int _regulator_disable(struct regulator_dev *rdev)* regulator_disable - disable regulator output * @regulator: regulator source * -* Disable the regulator output voltage or current. +* Disable the regulator output voltage or current. Calls to +* regulator_enable() must be balanced with calls to +* regulator_disable(). * * NOTE: this will only disable the regulator output if no other consumer -* devices have it enabled. Calls to regulator_enable() must be balanced with -* calls to regulator_disable(). +* devices have it enabled, the regulator device supports disabling and +* machine constraints permit this operation. */ int regulator_disable (struct regulator *regulator) {
@@ -1936,7 +1940,7 @@ void regulator_unregister(struct regulator_dev *rdev)EXPORT_SYMBOL_GPL (regulator_unregister);/** -* regulator_suspend_prepare: prepare regulators for system wide suspend +* regulator_suspend_prepare - prepare regulators for system wide suspend * @state: system suspend state * * Configure each regulator with it's suspend operating parameters for state.
Signature · 1 line
1.5.6.3
PATCH 5/5 regulator: Add basic DocBook manual
Add a basic DocBook manual for the regulator API. This is much more skeletal than the existing text documentation, the main benefit is to provide a skeleton for automatic generation of a manual based on the kerneldoc for the API.
Since large portions of the text are lifted from the existing text format documentation written by Liam Girdwood much of the credit belongs to him.
---
As I said in the covering message for the series I'm not sure if this is worthwhile or not - the plain text documentation is more complete, the main purpose of this was to make it easier to generate the kerneldoc so I could do the earlier parts of the series.
I'm also fairly hopeless at proofreading my own text.
Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/regulator.tmpl | 304 ++++++++++++++++++++++++++++++++++ 2 files changed, 305 insertions(+), 1 deletions(-) create mode 100644 Documentation/DocBook/regulator.tmpl
Documentation/DocBook/Makefile +1 -1
@@ -12,7 +12,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ - mac80211.xml debugobjects.xml sh.xml + mac80211.xml debugobjects.xml sh.xml regulator.xml ### # The build process is as follows (targets):
Documentation/DocBook/regulator.tmpl new file +304 -0
304 lines not on this page · raw message
Signature · 1 line
1.5.6.3
Liam Girdwood
AppliedQuoted 9 lines · Mark Brown
This patch series cleans up the kerneldoc for the regulator API and adds a brief DocBook manual for it, based heavily on the existing plain text documentation but much less complete. I'm not sure that the manual itself is actually worthwhile, the main benefit from it is the generated documentation rather than the text in the manual itself - I did the work to help with generating the earlier fixes.
It may be worth considering the first four patches for 2.6.29 as fixes, though it's questionable.
Applied.
Thanks
Liam