libertas: use kernel-doc notation, fix comment style

Convert all libertas/ files to use kernel-doc notation instead
of whatever it was (doxygen?).

Add or fix function parameters in several places.

Use expected style for multi-line comments in lots of places.

Remove erroneous /** in multiple places.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Acked-by: Dan Williams <dcbw@redhat.com>
Signed-off-by: John W. Linville <linville@tuxdriver.com>

1 files changed, 127 insertions, 118 deletions

diff --git a/drivers/net/wireless/libertas/cmd.c b/drivers/net/wireless/libertas/cmd.c
index 7e8a658b7670..6a96fc9c1cea 100644
--- a/drivers/net/wireless/libertas/cmd.c
+++ b/drivers/net/wireless/libertas/cmd.c
@@ -1,7 +1,7 @@
-/**
-  * This file contains the handling of command.
-  * It prepares command and sends it to firmware when it is ready.
-  */
+/*
+ * This file contains the handling of command.
+ * It prepares command and sends it to firmware when it is ready.
+ */
 
 #include <linux/kfifo.h>
 #include <linux/sched.h>
@@ -16,14 +16,14 @@
 #define CAL_RSSI(snr, nf)	((s32)((s32)(snr) + CAL_NF(nf)))
 
 /**
- *  @brief Simple callback that copies response back into command
+ * lbs_cmd_copyback - Simple callback that copies response back into command
  *
- *  @param priv    	A pointer to struct lbs_private structure
- *  @param extra  	A pointer to the original command structure for which
- *                      'resp' is a response
- *  @param resp         A pointer to the command response
+ * @priv:	A pointer to &struct lbs_private structure
+ * @extra:	A pointer to the original command structure for which
+ *		'resp' is a response
+ * @resp:	A pointer to the command response
  *
- *  @return 	   	0 on success, error on failure
+ * returns:	0 on success, error on failure
  */
 int lbs_cmd_copyback(struct lbs_private *priv, unsigned long extra,
 		     struct cmd_header *resp)
@@ -38,15 +38,15 @@ int lbs_cmd_copyback(struct lbs_private *priv, unsigned long extra,
 EXPORT_SYMBOL_GPL(lbs_cmd_copyback);
 
 /**
- *  @brief Simple callback that ignores the result. Use this if
- *  you just want to send a command to the hardware, but don't
+ *  lbs_cmd_async_callback - Simple callback that ignores the result.
+ *  Use this if you just want to send a command to the hardware, but don't
  *  care for the result.
  *
- *  @param priv         ignored
- *  @param extra        ignored
- *  @param resp         ignored
+ *  @priv:	ignored
+ *  @extra:	ignored
+ *  @resp:	ignored
  *
- *  @return 	   	0 for success
+ *  returns:	0 for success
  */
 static int lbs_cmd_async_callback(struct lbs_private *priv, unsigned long extra,
 		     struct cmd_header *resp)
@@ -56,10 +56,11 @@ static int lbs_cmd_async_callback(struct lbs_private *priv, unsigned long extra,
 
 
 /**
- *  @brief Checks whether a command is allowed in Power Save mode
+ *  is_command_allowed_in_ps - tests if a command is allowed in Power Save mode
+ *
+ *  @cmd:	the command ID
  *
- *  @param command the command ID
- *  @return 	   1 if allowed, 0 if not allowed
+ *  returns:	1 if allowed, 0 if not allowed
  */
 static u8 is_command_allowed_in_ps(u16 cmd)
 {
@@ -75,11 +76,12 @@ static u8 is_command_allowed_in_ps(u16 cmd)
 }
 
 /**
- *  @brief Updates the hardware details like MAC address and regulatory region
+ *  lbs_update_hw_spec - Updates the hardware details like MAC address
+ *  and regulatory region
  *
- *  @param priv    	A pointer to struct lbs_private structure
+ *  @priv:	A pointer to &struct lbs_private structure
  *
- *  @return 	   	0 on success, error on failure
+ *  returns:	0 on success, error on failure
  */
 int lbs_update_hw_spec(struct lbs_private *priv)
 {
@@ -217,14 +219,14 @@ int lbs_host_sleep_cfg(struct lbs_private *priv, uint32_t criteria,
 EXPORT_SYMBOL_GPL(lbs_host_sleep_cfg);
 
 /**
- *  @brief Sets the Power Save mode
+ *  lbs_set_ps_mode - Sets the Power Save mode
  *
- *  @param priv    	A pointer to struct lbs_private structure
- *  @param cmd_action	The Power Save operation (PS_MODE_ACTION_ENTER_PS or
+ *  @priv:	A pointer to &struct lbs_private structure
+ *  @cmd_action: The Power Save operation (PS_MODE_ACTION_ENTER_PS or
  *                         PS_MODE_ACTION_EXIT_PS)
- *  @param block	Whether to block on a response or not
+ *  @block:	Whether to block on a response or not
  *
- *  @return 	   	0 on success, error on failure
+ *  returns:	0 on success, error on failure
  */
 int lbs_set_ps_mode(struct lbs_private *priv, u16 cmd_action, bool block)
 {
@@ -417,13 +419,13 @@ int lbs_set_host_sleep(struct lbs_private *priv, int host_sleep)
 }
 
 /**
- *  @brief Set an SNMP MIB value
+ *  lbs_set_snmp_mib - Set an SNMP MIB value
  *
- *  @param priv    	A pointer to struct lbs_private structure
- *  @param oid  	The OID to set in the firmware
- *  @param val  	Value to set the OID to
+ *  @priv:	A pointer to &struct lbs_private structure
+ *  @oid:	The OID to set in the firmware
+ *  @val:	Value to set the OID to
  *
- *  @return 	   	0 on success, error on failure
+ *  returns: 	   	0 on success, error on failure
  */
 int lbs_set_snmp_mib(struct lbs_private *priv, u32 oid, u16 val)
 {
@@ -467,13 +469,13 @@ out:
 }
 
 /**
- *  @brief Get an SNMP MIB value
+ *  lbs_get_snmp_mib - Get an SNMP MIB value
  *
- *  @param priv    	A pointer to struct lbs_private structure
- *  @param oid  	The OID to retrieve from the firmware
- *  @param out_val  	Location for the returned value
+ *  @priv:	A pointer to &struct lbs_private structure
+ *  @oid:	The OID to retrieve from the firmware
+ *  @out_val:	Location for the returned value
  *
- *  @return 	   	0 on success, error on failure
+ *  returns:	0 on success, error on failure
  */
 int lbs_get_snmp_mib(struct lbs_private *priv, u32 oid, u16 *out_val)
 {
@@ -510,14 +512,14 @@ out:
 }
 
 /**
- *  @brief Get the min, max, and current TX power
+ *  lbs_get_tx_power - Get the min, max, and current TX power
  *
- *  @param priv    	A pointer to struct lbs_private structure
- *  @param curlevel  	Current power level in dBm
- *  @param minlevel  	Minimum supported power level in dBm (optional)
- *  @param maxlevel  	Maximum supported power level in dBm (optional)
+ *  @priv:	A pointer to &struct lbs_private structure
+ *  @curlevel:	Current power level in dBm
+ *  @minlevel:	Minimum supported power level in dBm (optional)
+ *  @maxlevel:	Maximum supported power level in dBm (optional)
  *
- *  @return 	   	0 on success, error on failure
+ *  returns:	0 on success, error on failure
  */
 int lbs_get_tx_power(struct lbs_private *priv, s16 *curlevel, s16 *minlevel,
 		     s16 *maxlevel)
@@ -545,12 +547,12 @@ int lbs_get_tx_power(struct lbs_private *priv, s16 *curlevel, s16 *minlevel,
 }
 
 /**
- *  @brief Set the TX power
+ *  lbs_set_tx_power - Set the TX power
  *
- *  @param priv    	A pointer to struct lbs_private structure
- *  @param dbm  	The desired power level in dBm
+ *  @priv:	A pointer to &struct lbs_private structure
+ *  @dbm:	The desired power level in dBm
  *
- *  @return 	   	0 on success, error on failure
+ *  returns: 	   	0 on success, error on failure
  */
 int lbs_set_tx_power(struct lbs_private *priv, s16 dbm)
 {
@@ -573,12 +575,13 @@ int lbs_set_tx_power(struct lbs_private *priv, s16 dbm)
 }
 
 /**
- *  @brief Enable or disable monitor mode (only implemented on OLPC usb8388 FW)
+ *  lbs_set_monitor_mode - Enable or disable monitor mode
+ *  (only implemented on OLPC usb8388 FW)
  *
- *  @param priv        A pointer to struct lbs_private structure
- *  @param enable      1 to enable monitor mode, 0 to disable
+ *  @priv:	A pointer to &struct lbs_private structure
+ *  @enable:	1 to enable monitor mode, 0 to disable
  *
- *  @return            0 on success, error on failure
+ *  returns:	0 on success, error on failure
  */
 int lbs_set_monitor_mode(struct lbs_private *priv, int enable)
 {
@@ -604,11 +607,11 @@ int lbs_set_monitor_mode(struct lbs_private *priv, int enable)
 }
 
 /**
- *  @brief Get the radio channel
+ *  lbs_get_channel - Get the radio channel
  *
- *  @param priv    	A pointer to struct lbs_private structure
+ *  @priv:	A pointer to &struct lbs_private structure
  *
- *  @return 	   	The channel on success, error on failure
+ *  returns:	The channel on success, error on failure
  */
 static int lbs_get_channel(struct lbs_private *priv)
 {
@@ -650,12 +653,12 @@ int lbs_update_channel(struct lbs_private *priv)
 }
 
 /**
- *  @brief Set the radio channel
+ *  lbs_set_channel - Set the radio channel
  *
- *  @param priv    	A pointer to struct lbs_private structure
- *  @param channel  	The desired channel, or 0 to clear a locked channel
+ *  @priv:	A pointer to &struct lbs_private structure
+ *  @channel:	The desired channel, or 0 to clear a locked channel
  *
- *  @return 	   	0 on success, error on failure
+ *  returns:	0 on success, error on failure
  */
 int lbs_set_channel(struct lbs_private *priv, u8 channel)
 {
@@ -686,12 +689,13 @@ out:
 }
 
 /**
- *  @brief Get current RSSI and noise floor
+ * lbs_get_rssi - Get current RSSI and noise floor
  *
- *  @param priv		A pointer to struct lbs_private structure
- *  @param rssi		On successful return, signal level in mBm
+ * @priv:	A pointer to &struct lbs_private structure
+ * @rssi:	On successful return, signal level in mBm
+ * @nf:		On successful return, Noise floor
  *
- *  @return 	   	The channel on success, error on failure
+ * returns:	The channel on success, error on failure
  */
 int lbs_get_rssi(struct lbs_private *priv, s8 *rssi, s8 *nf)
 {
@@ -719,13 +723,14 @@ int lbs_get_rssi(struct lbs_private *priv, s8 *rssi, s8 *nf)
 }
 
 /**
- *  @brief Send regulatory and 802.11d domain information to the firmware
+ *  lbs_set_11d_domain_info - Send regulatory and 802.11d domain information
+ *  to the firmware
  *
- *  @param priv		pointer to struct lbs_private
- *  @param request	cfg80211 regulatory request structure
- *  @param bands	the device's supported bands and channels
+ *  @priv:	pointer to &struct lbs_private
+ *  @request:	cfg80211 regulatory request structure
+ *  @bands:	the device's supported bands and channels
  *
- *  @return		0 on success, error code on failure
+ *  returns:	0 on success, error code on failure
 */
 int lbs_set_11d_domain_info(struct lbs_private *priv,
 			    struct regulatory_request *request,
@@ -842,15 +847,15 @@ int lbs_set_11d_domain_info(struct lbs_private *priv,
 }
 
 /**
- *  @brief Read a MAC, Baseband, or RF register
+ *  lbs_get_reg - Read a MAC, Baseband, or RF register
  *
- *  @param priv		pointer to struct lbs_private
- *  @param cmd		register command, one of CMD_MAC_REG_ACCESS,
- *                        CMD_BBP_REG_ACCESS, or CMD_RF_REG_ACCESS
- *  @param offset       byte offset of the register to get
- *  @param value        on success, the value of the register at 'offset'
+ *  @priv:	pointer to &struct lbs_private
+ *  @reg:	register command, one of CMD_MAC_REG_ACCESS,
+ *		CMD_BBP_REG_ACCESS, or CMD_RF_REG_ACCESS
+ *  @offset:	byte offset of the register to get
+ *  @value:	on success, the value of the register at 'offset'
  *
- *  @return		0 on success, error code on failure
+ *  returns:	0 on success, error code on failure
 */
 int lbs_get_reg(struct lbs_private *priv, u16 reg, u16 offset, u32 *value)
 {
@@ -886,15 +891,15 @@ out:
 }
 
 /**
- *  @brief Write a MAC, Baseband, or RF register
+ *  lbs_set_reg - Write a MAC, Baseband, or RF register
  *
- *  @param priv		pointer to struct lbs_private
- *  @param cmd		register command, one of CMD_MAC_REG_ACCESS,
- *                        CMD_BBP_REG_ACCESS, or CMD_RF_REG_ACCESS
- *  @param offset       byte offset of the register to set
- *  @param value        the value to write to the register at 'offset'
+ *  @priv:	pointer to &struct lbs_private
+ *  @reg:	register command, one of CMD_MAC_REG_ACCESS,
+ *		CMD_BBP_REG_ACCESS, or CMD_RF_REG_ACCESS
+ *  @offset:	byte offset of the register to set
+ *  @value:	the value to write to the register at 'offset'
  *
- *  @return		0 on success, error code on failure
+ *  returns:	0 on success, error code on failure
 */
 int lbs_set_reg(struct lbs_private *priv, u16 reg, u16 offset, u32 value)
 {
@@ -1023,7 +1028,7 @@ static void lbs_submit_command(struct lbs_private *priv,
 	lbs_deb_leave(LBS_DEB_HOST);
 }
 
-/**
+/*
  *  This function inserts command node to cmdfreeq
  *  after cleans it. Requires priv->driver_lock held.
  */
@@ -1125,11 +1130,12 @@ void lbs_set_mac_control(struct lbs_private *priv)
 }
 
 /**
- *  @brief This function allocates the command buffer and link
- *  it to command free queue.
+ *  lbs_allocate_cmd_buffer - allocates the command buffer and links
+ *  it to command free queue
+ *
+ *  @priv:	A pointer to &struct lbs_private structure
  *
- *  @param priv		A pointer to struct lbs_private structure
- *  @return 		0 or -1
+ *  returns:	0 for success or -1 on error
  */
 int lbs_allocate_cmd_buffer(struct lbs_private *priv)
 {
@@ -1171,10 +1177,11 @@ done:
 }
 
 /**
- *  @brief This function frees the command buffer.
+ *  lbs_free_cmd_buffer - free the command buffer
  *
- *  @param priv		A pointer to struct lbs_private structure
- *  @return 		0 or -1
+ *  @priv:	A pointer to &struct lbs_private structure
+ *
+ *  returns:	0 for success
  */
 int lbs_free_cmd_buffer(struct lbs_private *priv)
 {
@@ -1211,11 +1218,13 @@ done:
 }
 
 /**
- *  @brief This function gets a free command node if available in
- *  command free queue.
+ *  lbs_get_free_cmd_node - gets a free command node if available in
+ *  command free queue
+ *
+ *  @priv:	A pointer to &struct lbs_private structure
  *
- *  @param priv		A pointer to struct lbs_private structure
- *  @return cmd_ctrl_node A pointer to cmd_ctrl_node structure or NULL
+ *  returns:	A pointer to &cmd_ctrl_node structure on success
+ *		or %NULL on error
  */
 static struct cmd_ctrl_node *lbs_get_free_cmd_node(struct lbs_private *priv)
 {
@@ -1245,12 +1254,12 @@ static struct cmd_ctrl_node *lbs_get_free_cmd_node(struct lbs_private *priv)
 }
 
 /**
- *  @brief This function executes next command in command
- *  pending queue. It will put firmware back to PS mode
- *  if applicable.
+ *  lbs_execute_next_command - execute next command in command
+ *  pending queue. Will put firmware back to PS mode if applicable.
  *
- *  @param priv     A pointer to struct lbs_private structure
- *  @return 	   0 or -1
+ *  @priv:	A pointer to &struct lbs_private structure
+ *
+ *  returns:	0 on success or -1 on error
  */
 int lbs_execute_next_command(struct lbs_private *priv)
 {
@@ -1454,12 +1463,12 @@ out:
 }
 
 /**
- *  @brief This function checks condition and prepares to
- *  send sleep confirm command to firmware if ok.
+ * lbs_ps_confirm_sleep - checks condition and prepares to
+ * send sleep confirm command to firmware if ok
+ *
+ * @priv:	A pointer to &struct lbs_private structure
  *
- *  @param priv    	A pointer to struct lbs_private structure
- *  @param psmode  	Power Saving mode
- *  @return 	   	n/a
+ * returns:	n/a
  */
 void lbs_ps_confirm_sleep(struct lbs_private *priv)
 {
@@ -1499,16 +1508,16 @@ void lbs_ps_confirm_sleep(struct lbs_private *priv)
 
 
 /**
- * @brief Configures the transmission power control functionality.
+ * lbs_set_tpc_cfg - Configures the transmission power control functionality
  *
- * @param priv		A pointer to struct lbs_private structure
- * @param enable	Transmission power control enable
- * @param p0		Power level when link quality is good (dBm).
- * @param p1		Power level when link quality is fair (dBm).
- * @param p2		Power level when link quality is poor (dBm).
- * @param usesnr	Use Signal to Noise Ratio in TPC
+ * @priv:	A pointer to &struct lbs_private structure
+ * @enable:	Transmission power control enable
+ * @p0:		Power level when link quality is good (dBm).
+ * @p1:		Power level when link quality is fair (dBm).
+ * @p2:		Power level when link quality is poor (dBm).
+ * @usesnr:	Use Signal to Noise Ratio in TPC
  *
- * @return 0 on success
+ * returns:	0 on success
  */
 int lbs_set_tpc_cfg(struct lbs_private *priv, int enable, int8_t p0, int8_t p1,
 		int8_t p2, int usesnr)
@@ -1531,15 +1540,15 @@ int lbs_set_tpc_cfg(struct lbs_private *priv, int enable, int8_t p0, int8_t p1,
 }
 
 /**
- * @brief Configures the power adaptation settings.
+ * lbs_set_power_adapt_cfg - Configures the power adaptation settings
  *
- * @param priv		A pointer to struct lbs_private structure
- * @param enable	Power adaptation enable
- * @param p0		Power level for 1, 2, 5.5 and 11 Mbps (dBm).
- * @param p1		Power level for 6, 9, 12, 18, 22, 24 and 36 Mbps (dBm).
- * @param p2		Power level for 48 and 54 Mbps (dBm).
+ * @priv:	A pointer to &struct lbs_private structure
+ * @enable:	Power adaptation enable
+ * @p0:		Power level for 1, 2, 5.5 and 11 Mbps (dBm).
+ * @p1:		Power level for 6, 9, 12, 18, 22, 24 and 36 Mbps (dBm).
+ * @p2:		Power level for 48 and 54 Mbps (dBm).
  *
- * @return 0 on Success
+ * returns:	0 on Success
  */
 
 int lbs_set_power_adapt_cfg(struct lbs_private *priv, int enable, int8_t p0,