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, 53 insertions, 46 deletions

diff --git a/drivers/net/wireless/libertas/main.c b/drivers/net/wireless/libertas/main.c
index ca8149cd5bd9..ed57cf863b69 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 @@ EXPORT_SYMBOL_GPL(lbs_debug);
 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 @@ static u8 fw_data_rates[MAX_RATES] =
 };
 
 /**
- *  @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 @@ u32 lbs_fw_index_to_data_rate(u8 idx)
 }
 
 /**
- *  @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 @@ u8 lbs_data_rate_to_fw_index(u32 rate)
 
 
 /**
- *  @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 @@ static int lbs_dev_open(struct net_device *dev)
 }
 
 /**
- *  @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 @@ void lbs_set_multicast_list(struct net_device *dev)
 }
 
 /**
- *  @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 @@ static int lbs_thread(void *data)
 }
 
 /**
- * @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 @@ int lbs_resume(struct lbs_private *priv)
 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 @@ out:
 }
 
 /**
- *  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 @@ static const struct net_device_ops lbs_netdev_ops = {
 };
 
 /**
- * @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 @@ void lbs_notify_command_response(struct lbs_private *priv, u8 resp_idx)
 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,