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>
diff --git a/drivers/net/wireless/libertas/main.c b/drivers/net/wireless/libertas/main.c
index ca8149c..ed57cf8 100644
--- a/drivers/net/wireless/libertas/main.c
+++ b/drivers/net/wireless/libertas/main.c
@@ -1,8 +1,8 @@
-/**
- * This file contains the major functions in WLAN
- * driver. It includes init, exit, open, close and main
- * thread etc..
- */
+/*
+ * This file contains the major functions in WLAN
+ * driver. It includes init, exit, open, close and main
+ * thread etc..
+ */
#include <linux/moduleparam.h>
#include <linux/delay.h>
@@ -35,18 +35,20 @@
module_param_named(libertas_debug, lbs_debug, int, 0644);
-/* This global structure is used to send the confirm_sleep command as
- * fast as possible down to the firmware. */
+/*
+ * This global structure is used to send the confirm_sleep command as
+ * fast as possible down to the firmware.
+ */
struct cmd_confirm_sleep confirm_sleep;
-/**
+/*
* the table to keep region code
*/
u16 lbs_region_code_to_index[MRVDRV_MAX_REGION_CODE] =
{ 0x10, 0x20, 0x30, 0x31, 0x32, 0x40 };
-/**
+/*
* FW rate table. FW refers to rates by their index in this table, not by the
* rate value itself. Values of 0x00 are
* reserved positions.
@@ -57,10 +59,10 @@
};
/**
- * @brief use index to get the data rate
+ * lbs_fw_index_to_data_rate - use index to get the data rate
*
- * @param idx The index of data rate
- * @return data rate or 0
+ * @idx: The index of data rate
+ * returns: data rate or 0
*/
u32 lbs_fw_index_to_data_rate(u8 idx)
{
@@ -70,10 +72,10 @@
}
/**
- * @brief use rate to get the index
+ * lbs_data_rate_to_fw_index - use rate to get the index
*
- * @param rate data rate
- * @return index or 0
+ * @rate: data rate
+ * returns: index or 0
*/
u8 lbs_data_rate_to_fw_index(u32 rate)
{
@@ -91,10 +93,10 @@
/**
- * @brief This function opens the ethX interface
+ * lbs_dev_open - open the ethX interface
*
- * @param dev A pointer to net_device structure
- * @return 0 or -EBUSY if monitor mode active
+ * @dev: A pointer to &net_device structure
+ * returns: 0 or -EBUSY if monitor mode active
*/
static int lbs_dev_open(struct net_device *dev)
{
@@ -120,10 +122,10 @@
}
/**
- * @brief This function closes the ethX interface
+ * lbs_eth_stop - close the ethX interface
*
- * @param dev A pointer to net_device structure
- * @return 0
+ * @dev: A pointer to &net_device structure
+ * returns: 0
*/
static int lbs_eth_stop(struct net_device *dev)
{
@@ -336,12 +338,12 @@
}
/**
- * @brief This function handles the major jobs in the LBS driver.
+ * lbs_thread - handles the major jobs in the LBS driver.
* It handles all events generated by firmware, RX data received
* from firmware and TX data sent from kernel.
*
- * @param data A pointer to lbs_thread structure
- * @return 0
+ * @data: A pointer to &lbs_thread structure
+ * returns: 0
*/
static int lbs_thread(void *data)
{
@@ -540,11 +542,11 @@
}
/**
- * @brief This function gets the HW spec from the firmware and sets
- * some basic parameters.
+ * lbs_setup_firmware - gets the HW spec from the firmware and sets
+ * some basic parameters
*
- * @param priv A pointer to struct lbs_private structure
- * @return 0 or -1
+ * @priv: A pointer to &struct lbs_private structure
+ * returns: 0 or -1
*/
static int lbs_setup_firmware(struct lbs_private *priv)
{
@@ -630,8 +632,10 @@
EXPORT_SYMBOL_GPL(lbs_resume);
/**
- * This function handles the timeout of command sending.
- * It will re-send the same command again.
+ * lbs_cmd_timeout_handler - handles the timeout of command sending.
+ * It will re-send the same command again.
+ *
+ * @data: &struct lbs_private pointer
*/
static void lbs_cmd_timeout_handler(unsigned long data)
{
@@ -655,8 +659,10 @@
}
/**
- * This function put the device back to deep sleep mode when timer expires
- * and no activity (command, event, data etc.) is detected.
+ * auto_deepsleep_timer_fn - put the device back to deep sleep mode when
+ * timer expires and no activity (command, event, data etc.) is detected.
+ * @data: &struct lbs_private pointer
+ * returns: N/A
*/
static void auto_deepsleep_timer_fn(unsigned long data)
{
@@ -792,11 +798,12 @@
};
/**
- * @brief This function adds the card. it will probe the
+ * lbs_add_card - adds the card. It will probe the
* card, allocate the lbs_priv and initialize the device.
*
- * @param card A pointer to card
- * @return A pointer to struct lbs_private structure
+ * @card: A pointer to card
+ * @dmdev: A pointer to &struct device
+ * returns: A pointer to &struct lbs_private structure
*/
struct lbs_private *lbs_add_card(void *card, struct device *dmdev)
{
@@ -1057,19 +1064,19 @@
EXPORT_SYMBOL_GPL(lbs_notify_command_response);
/**
- * @brief Retrieves two-stage firmware
+ * lbs_get_firmware - Retrieves two-stage firmware
*
- * @param dev A pointer to device structure
- * @param user_helper User-defined helper firmware file
- * @param user_mainfw User-defined main firmware file
- * @param card_model Bus-specific card model ID used to filter firmware table
- * elements
- * @param fw_table Table of firmware file names and device model numbers
- * terminated by an entry with a NULL helper name
- * @param helper On success, the helper firmware; caller must free
- * @param mainfw On success, the main firmware; caller must free
+ * @dev: A pointer to &device structure
+ * @user_helper: User-defined helper firmware file
+ * @user_mainfw: User-defined main firmware file
+ * @card_model: Bus-specific card model ID used to filter firmware table
+ * elements
+ * @fw_table: Table of firmware file names and device model numbers
+ * terminated by an entry with a NULL helper name
+ * @helper: On success, the helper firmware; caller must free
+ * @mainfw: On success, the main firmware; caller must free
*
- * @return 0 on success, non-zero on failure
+ * returns: 0 on success, non-zero on failure
*/
int lbs_get_firmware(struct device *dev, const char *user_helper,
const char *user_mainfw, u32 card_model,