edac: fix kernel-doc tags at the drivers/edac_*.h

Some kernel-doc tags don't provide good descriptions or use
a different style. Adjust them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

diff --git a/Documentation/admin-guide/ras.rst b/Documentation/admin-guide/ras.rst
index 2f8706bae5a40038f0e1a002b50d6c3695362d4b..d71340e86c27590ff139d309b57e37d755c8dfd7 100644 (file)
--- a/Documentation/admin-guide/ras.rst
+++ b/Documentation/admin-guide/ras.rst
@@ -843,7 +843,7 @@ Module parameters
 EDAC device type
 ----------------
 
-In the header file, edac_core.h, there is a series of edac_device structures
+In the header file, edac_pci.h, there is a series of edac_device structures
 and APIs for the EDAC_DEVICE.
 
 User space access to an edac_device is through the sysfs interface.

diff --git a/drivers/edac/edac_mc.h b/drivers/edac/edac_mc.h
index dcc2c7e3b8bcd3d0c8fe2a2576007c2fedbe2572..50fc1dc9c0d837b2d661c1d6af1e3f2ff563adff 100644 (file)
--- a/drivers/edac/edac_mc.h
+++ b/drivers/edac/edac_mc.h
@@ -15,6 +15,8 @@
  * Refactored for multi-source files:
  *     Doug Thompson <norsk5@xmission.com>
  *
+ * Please look at Documentation/driver-api/edac.rst for more info about
+ * EDAC core structs and functions.
  */
 
 #ifndef _EDAC_MC_H_
@@ -94,7 +96,8 @@ do {                                                                  \
 #define to_mci(k) container_of(k, struct mem_ctl_info, dev)
 
 /**
- * edac_mc_alloc: Allocate and partially fill a struct mem_ctl_info structure
+ * edac_mc_alloc() - Allocate and partially fill a struct &mem_ctl_info.
+ *
  * @mc_num:            Memory controller number
  * @n_layers:          Number of MC hierarchy layers
  * @layers:            Describes each layer as seen by the Memory Controller
@@ -116,8 +119,8 @@ do {                                                                        \
  *   on such scenarios, as grouping the multiple ranks require drivers change.
  *
  * Returns:
- *     On failure: NULL
- *     On success: struct mem_ctl_info pointer
+ *     On success, return a pointer to struct mem_ctl_info pointer;
+ *     %NULL otherwise
  */
 struct mem_ctl_info *edac_mc_alloc(unsigned mc_num,
                                   unsigned n_layers,
@@ -125,28 +128,28 @@ struct mem_ctl_info *edac_mc_alloc(unsigned mc_num,
                                   unsigned sz_pvt);
 
 /**
- * edac_mc_add_mc_with_groups: Insert the 'mci' structure into the mci
- *     global list and create sysfs entries associated with mci structure
+ * edac_mc_add_mc_with_groups() - Insert the @mci structure into the mci
+ *     global list and create sysfs entries associated with @mci structure.
+ *
  * @mci: pointer to the mci structure to be added to the list
  * @groups: optional attribute groups for the driver-specific sysfs entries
  *
- * Return:
- *     0       Success
- *     !0      Failure
+ * Returns:
+ *     0 on Success, or an error code on failure
  */
 extern int edac_mc_add_mc_with_groups(struct mem_ctl_info *mci,
                                      const struct attribute_group **groups);
 #define edac_mc_add_mc(mci)    edac_mc_add_mc_with_groups(mci, NULL)
 
 /**
- * edac_mc_free
- *     'Free' a previously allocated 'mci' structure
+ * edac_mc_free() -  Frees a previously allocated @mci structure
+ *
  * @mci: pointer to a struct mem_ctl_info structure
  */
 extern void edac_mc_free(struct mem_ctl_info *mci);
 
 /**
- * edac_mc_find: Search for a mem_ctl_info structure whose index is @idx.
+ * edac_mc_find() - Search for a mem_ctl_info structure whose index is @idx.
  *
  * @idx: index to be seek
  *
@@ -156,29 +159,41 @@ extern void edac_mc_free(struct mem_ctl_info *mci);
 extern struct mem_ctl_info *edac_mc_find(int idx);
 
 /**
- * find_mci_by_dev
+ * find_mci_by_dev() - Scan list of controllers looking for the one that
+ *     manages the @dev device.
  *
- *     scan list of controllers looking for the one that manages
- *     the 'dev' device
  * @dev: pointer to a struct device related with the MCI
+ *
+ * Returns: on success, returns a pointer to struct &mem_ctl_info;
+ * %NULL otherwise.
  */
 extern struct mem_ctl_info *find_mci_by_dev(struct device *dev);
 
 /**
- * edac_mc_del_mc: Remove sysfs entries for specified mci structure and
- *                 remove mci structure from global list
+ * edac_mc_del_mc() - Remove sysfs entries for mci structure associated with
+ *     @dev and remove mci structure from global list.
  *
  * @dev: Pointer to struct &device representing mci structure to remove.
  *
- * Returns: pointer to removed mci structure, or NULL if device not found.
+ * Returns: pointer to removed mci structure, or %NULL if device not found.
  */
 extern struct mem_ctl_info *edac_mc_del_mc(struct device *dev);
+
+/**
+ * edac_mc_find_csrow_by_page() - Ancillary routine to identify what csrow
+ *     contains a memory page.
+ *
+ * @mci: pointer to a struct mem_ctl_info structure
+ * @page: memory page to find
+ *
+ * Returns: on success, returns the csrow. -1 if not found.
+ */
 extern int edac_mc_find_csrow_by_page(struct mem_ctl_info *mci,
                                      unsigned long page);
 
 /**
- * edac_raw_mc_handle_error - reports a memory event to userspace without doing
- *                           anything to discover the error location
+ * edac_raw_mc_handle_error() - Reports a memory event to userspace without
+ *     doing anything to discover the error location.
  *
  * @type:              severity of the error (CE/UE/Fatal)
  * @mci:               a struct mem_ctl_info pointer
@@ -193,7 +208,7 @@ void edac_raw_mc_handle_error(const enum hw_event_mc_err_type type,
                              struct edac_raw_error_desc *e);
 
 /**
- * edac_mc_handle_error - reports a memory event to userspace
+ * edac_mc_handle_error() - Reports a memory event to userspace.
  *
  * @type:              severity of the error (CE/UE/Fatal)
  * @mci:               a struct mem_ctl_info pointer