[U-Boot] [PATCH] pinctrl: Fix a bunch of broken kernel-doc in drivers/pinctrl
Robert P. J. Day
rpjday at crashcourse.ca
Tue May 24 14:39:33 CEST 2016
Adjust kernel-doc content to be semantically valid, and fix a few
typos while we're there.
Signed-off-by: Robert P. J. Day <rpjday at crashcourse.ca>
---
there is still some broken kernel-doc in that directory, such as
this in pinctrl_rk3288.c:
/**
* @type: iomux variant using IOMUX_* constants
* @offset: if initialized to -1 it will be autocalculated, by specifying
* an initial offset value the relevant source offset can be reset
* to a new value for autocalculating the following iomux registers.
*/
struct rockchip_iomux {
u8 type;
s16 offset;
};
in the above, the kernel-doc is missing the leading structure name
line -- you need one of those just as you need one for functions, like
this:
/**
* struct blah - the basic blah structure
* @mem1: describe the first member of struct blah
* @mem2: describe the second member of struct blah,
* perhaps with more lines and words.
*
* Longer description of this structure.
*/
---
drivers/pinctrl/pinctrl-generic.c | 37 +++++++++++++++--------------
drivers/pinctrl/pinctrl-uclass.c | 26 ++++++++++----------
drivers/pinctrl/rockchip/pinctrl_rk3288.c | 2 +-
drivers/pinctrl/uniphier/pinctrl-uniphier.h | 4 ----
4 files changed, 34 insertions(+), 35 deletions(-)
diff --git a/drivers/pinctrl/pinctrl-generic.c b/drivers/pinctrl/pinctrl-generic.c
index e86b72a..80848ba 100644
--- a/drivers/pinctrl/pinctrl-generic.c
+++ b/drivers/pinctrl/pinctrl-generic.c
@@ -13,10 +13,10 @@ DECLARE_GLOBAL_DATA_PTR;
/**
* pinctrl_pin_name_to_selector() - return the pin selector for a pin
- *
* @dev: pin controller device
* @pin: the pin name to look up
- * @return: pin selector, or negative error code on failure
+ *
+ * Return: pin selector, or negative error code on failure
*/
static int pinctrl_pin_name_to_selector(struct udevice *dev, const char *pin)
{
@@ -43,10 +43,10 @@ static int pinctrl_pin_name_to_selector(struct udevice *dev, const char *pin)
/**
* pinctrl_group_name_to_selector() - return the group selector for a group
- *
* @dev: pin controller device
* @group: the pin group name to look up
- * @return: pin group selector, or negative error code on failure
+ *
+ * Return: pin group selector, or negative error code on failure
*/
static int pinctrl_group_name_to_selector(struct udevice *dev,
const char *group)
@@ -75,10 +75,10 @@ static int pinctrl_group_name_to_selector(struct udevice *dev,
#if CONFIG_IS_ENABLED(PINMUX)
/**
* pinmux_func_name_to_selector() - return the function selector for a function
- *
* @dev: pin controller device
* @function: the function name to look up
- * @return: function selector, or negative error code on failure
+ *
+ * Return: function selector, or negative error code on failure
*/
static int pinmux_func_name_to_selector(struct udevice *dev,
const char *function)
@@ -107,12 +107,12 @@ static int pinmux_func_name_to_selector(struct udevice *dev,
/**
* pinmux_enable_setting() - enable pin-mux setting for a certain pin/group
- *
* @dev: pin controller device
* @is_group: target of operation (true: pin group, false: pin)
* @selector: pin selector or group selector, depending on @is_group
* @func_selector: function selector
- * @return: 0 on success, or negative error code on failure
+ *
+ * Return: 0 on success, or negative error code on failure
*/
static int pinmux_enable_setting(struct udevice *dev, bool is_group,
unsigned selector, unsigned func_selector)
@@ -151,11 +151,11 @@ static int pinmux_enable_setting(struct udevice *dev, bool is_group,
#if CONFIG_IS_ENABLED(PINCONF)
/**
* pinconf_prop_name_to_param() - return parameter ID for a property name
- *
* @dev: pin controller device
* @property: property name in DTS, such as "bias-pull-up", "slew-rate", etc.
* @default_value: return default value in case no value is specified in DTS
- * @return: return pamater ID, or negative error code on failure
+ *
+ * Return: return parameter ID, or negative error code on failure
*/
static int pinconf_prop_name_to_param(struct udevice *dev,
const char *property, u32 *default_value)
@@ -184,13 +184,13 @@ static int pinconf_prop_name_to_param(struct udevice *dev,
/**
* pinconf_enable_setting() - apply pin configuration for a certain pin/group
- *
* @dev: pin controller device
* @is_group: target of operation (true: pin group, false: pin)
* @selector: pin selector or group selector, depending on @is_group
* @param: configuration paramter
* @argument: argument taken by some configuration parameters
- * @return: 0 on success, or negative error code on failure
+ *
+ * Return: 0 on success, or negative error code on failure
*/
static int pinconf_enable_setting(struct udevice *dev, bool is_group,
unsigned selector, unsigned param,
@@ -231,14 +231,15 @@ static int pinconf_enable_setting(struct udevice *dev, bool is_group,
/**
* pinctrl_generic_set_state_one() - set state for a certain pin/group
- * Apply all pin multiplexing and pin configurations specified by @config
- * for a given pin or pin group.
- *
* @dev: pin controller device
* @config: pseudo device pointing to config node
* @is_group: target of operation (true: pin group, false: pin)
* @selector: pin selector or group selector, depending on @is_group
- * @return: 0 on success, or negative error code on failure
+ *
+ * Apply all pin multiplexing and pin configurations specified by config
+ * for a given pin or pin group.
+ *
+ * Return: 0 on success, or negative error code on failure
*/
static int pinctrl_generic_set_state_one(struct udevice *dev,
struct udevice *config,
@@ -291,10 +292,10 @@ static int pinctrl_generic_set_state_one(struct udevice *dev,
/**
* pinctrl_generic_set_state_subnode() - apply all settings in config node
- *
* @dev: pin controller device
* @config: pseudo device pointing to config node
- * @return: 0 on success, or negative error code on failure
+ *
+ * Return: 0 on success, or negative error code on failure
*/
static int pinctrl_generic_set_state_subnode(struct udevice *dev,
struct udevice *config)
diff --git a/drivers/pinctrl/pinctrl-uclass.c b/drivers/pinctrl/pinctrl-uclass.c
index ccc5d30..1970620 100644
--- a/drivers/pinctrl/pinctrl-uclass.c
+++ b/drivers/pinctrl/pinctrl-uclass.c
@@ -30,9 +30,9 @@ int pinctrl_decode_pin_config(const void *blob, int node)
#if CONFIG_IS_ENABLED(PINCTRL_FULL)
/**
* pinctrl_config_one() - apply pinctrl settings for a single node
- *
* @config: pin configuration node
- * @return: 0 on success, or negative error code on failure
+ *
+ * Return: 0 on success, or negative error code on failure
*/
static int pinctrl_config_one(struct udevice *config)
{
@@ -56,10 +56,10 @@ static int pinctrl_config_one(struct udevice *config)
/**
* pinctrl_select_state_full() - full implementation of pinctrl_select_state
- *
* @dev: peripheral device
* @statename: state name, like "default"
- * @return: 0 on success, or negative error code on failure
+ *
+ * Return: 0 on success, or negative error code on failure
*/
static int pinctrl_select_state_full(struct udevice *dev, const char *statename)
{
@@ -113,11 +113,12 @@ static int pinctrl_select_state_full(struct udevice *dev, const char *statename)
}
/**
- * pinconfig_post-bind() - post binding for PINCONFIG uclass
+ * pinconfig_post_bind() - post binding for PINCONFIG uclass
+ * @dev: pinconfig device
+ *
* Recursively bind its children as pinconfig devices.
*
- * @dev: pinconfig device
- * @return: 0 on success, or negative error code on failure
+ * Return: 0 on success, or negative error code on failure
*/
static int pinconfig_post_bind(struct udevice *dev)
{
@@ -181,9 +182,9 @@ static int pinconfig_post_bind(struct udevice *dev)
/**
* pinctrl_select_state_simple() - simple implementation of pinctrl_select_state
- *
* @dev: peripheral device
- * @return: 0 on success, or negative error code on failure
+ *
+ * Return: 0 on success, or negative error code on failure
*/
static int pinctrl_select_state_simple(struct udevice *dev)
{
@@ -257,11 +258,12 @@ int pinctrl_get_gpio_mux(struct udevice *dev, int banknum, int index)
}
/**
- * pinconfig_post-bind() - post binding for PINCTRL uclass
+ * pinctrl_post_bind() - post binding for PINCTRL uclass
+ * @dev: pinctrl device
+ *
* Recursively bind child nodes as pinconfig devices in case of full pinctrl.
*
- * @dev: pinctrl device
- * @return: 0 on success, or negative error code on failure
+ * Return: 0 on success, or negative error code on failure
*/
static int pinctrl_post_bind(struct udevice *dev)
{
diff --git a/drivers/pinctrl/rockchip/pinctrl_rk3288.c b/drivers/pinctrl/rockchip/pinctrl_rk3288.c
index 7c769bd..47cfb31 100644
--- a/drivers/pinctrl/rockchip/pinctrl_rk3288.c
+++ b/drivers/pinctrl/rockchip/pinctrl_rk3288.c
@@ -27,7 +27,7 @@ struct rk3288_pinctrl_priv {
int num_banks;
};
-/**
+/*
* Encode variants of iomux registers into a type variable
*/
#define IOMUX_GPIO_ONLY BIT(0)
diff --git a/drivers/pinctrl/uniphier/pinctrl-uniphier.h b/drivers/pinctrl/uniphier/pinctrl-uniphier.h
index 2b43848..1f761da 100644
--- a/drivers/pinctrl/uniphier/pinctrl-uniphier.h
+++ b/drivers/pinctrl/uniphier/pinctrl-uniphier.h
@@ -25,7 +25,6 @@ static inline unsigned int uniphier_pin_get_iectrl(unsigned long data)
/**
* struct uniphier_pinctrl_pin - pin data for UniPhier SoC
- *
* @number: pin number
* @data: additional per-pin data
*/
@@ -36,7 +35,6 @@ struct uniphier_pinctrl_pin {
/**
* struct uniphier_pinctrl_group - pin group data for UniPhier SoC
- *
* @name: pin group name
* @pins: array of pins that belong to the group
* @num_pins: number of pins in the group
@@ -51,7 +49,6 @@ struct uniphier_pinctrl_group {
/**
* struct uniphier_pinctrl_socdata - SoC data for UniPhier pin controller
- *
* @pins: array of pin data
* @pins_count: number of pin data
* @groups: array of pin group data
@@ -92,7 +89,6 @@ struct uniphier_pinctrl_socdata {
/**
* struct uniphier_pinctrl_priv - private data for UniPhier pinctrl driver
- *
* @base: base address of the pinctrl device
* @socdata: SoC specific data
*/
--
2.5.5
rday
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
More information about the U-Boot
mailing list