docs: s390: unify and update s390dbf kdocs at debug.c

For non-static-inlines, debug.c already had non-compliant function
header docs. So move the pure prototype kdocs of
("s390: include/asm/debug.h add kerneldoc markups")
from debug.h to debug.c and merge them with the old function docs.
Also, I had the impression that kdoc typically is at the implementation
in the compile unit rather than at the prototype in the header file.

While at it, update the short kdoc description to distinguish the
different functions. And a few more consistency cleanups.

Added a new kdoc for debug_set_critical() since debug.h comments it
as part of the API.

Signed-off-by: Steffen Maier <maier@linux.ibm.com>
Acked-by: Christian Borntraeger <borntraeger@de.ibm.com>
Message-Id: <1562149189-1417-3-git-send-email-maier@linux.ibm.com>
Signed-off-by: Vasily Gorbik <gor@linux.ibm.com>

1 files changed, 15 insertions, 97 deletions

diff --git a/arch/s390/include/asm/debug.h b/arch/s390/include/asm/debug.h
index 02c36eedd780..310134015541 100644
--- a/arch/s390/include/asm/debug.h
+++ b/arch/s390/include/asm/debug.h
@@ -95,77 +95,19 @@ debug_entry_t *debug_exception_common(debug_info_t *id, int level,
 
 /* Debug Feature API: */
 
-/**
- * debug_register() - allocates memory for a debug log.
- *
- * @name:        Name of debug log (e.g. used for debugfs entry)
- * @pages:       Number of pages, which will be allocated per area
- * @nr_areas:    Number of debug areas
- * @buf_size:    Size of data area in each debug entry
- *
- * Return:
- * - Handler for generated debug area
- * - %NULL if register failed
- *
- * Must not be called within an interrupt handler.
- */
 debug_info_t *debug_register(const char *name, int pages, int nr_areas,
 			     int buf_size);
 
-/**
- * debug_register_mode() - allocates memory for a debug log.
- *
- * @name:	Name of debug log (e.g. used for debugfs entry)
- * @pages:	Number of pages, which will be allocated per area
- * @nr_areas:	Number of debug areas
- * @buf_size:	Size of data area in each debug entry
- * @mode:	File mode for debugfs files. E.g. S_IRWXUGO
- * @uid:	User ID for debugfs files. Currently only 0 is supported.
- * @gid:	Group ID for debugfs files. Currently only 0 is supported.
- *
- * Return:
- * - Handler for generated debug area
- * - %NULL if register failed
- *
- * Must not be called within an interrupt handler
- */
 debug_info_t *debug_register_mode(const char *name, int pages, int nr_areas,
 				  int buf_size, umode_t mode, uid_t uid,
 				  gid_t gid);
 
-/**
- * debug_unregister() - frees memory for a debug log and removes all
- *			registered debug
- * views.
- *
- * @id:		handle for debug log
- *
- * Return:
- *    none
- *
- * Must not be called within an interrupt handler
- */
 void debug_unregister(debug_info_t *id);
 
-/**
- * debug_set_level() -  Sets new actual debug level if new_level is valid.
- *
- * @id:		handle for debug log
- * @new_level:	new debug level
- *
- * Return:
- *    none
- */
 void debug_set_level(debug_info_t *id, int new_level);
 
 void debug_set_critical(void);
 
-/**
- * debug_stop_all() - stops the debug feature if stopping is allowed.
- *
- * Return:
- * -   none
- */
 void debug_stop_all(void);
 
 /**
@@ -184,7 +126,7 @@ static inline bool debug_level_enabled(debug_info_t *id, int level)
 }
 
 /**
- * debug_event() - writes debug entry to active debug area
+ * debug_event() - writes binary debug entry to active debug area
  *		   (if level <= actual debug level)
  *
  * @id:		handle for debug log
@@ -194,6 +136,7 @@ static inline bool debug_level_enabled(debug_info_t *id, int level)
  *
  * Return:
  * - Address of written debug entry
+ * - %NULL if error
  */
 static inline debug_entry_t *debug_event(debug_info_t *id, int level,
 					 void *data, int length)
@@ -204,7 +147,7 @@ static inline debug_entry_t *debug_event(debug_info_t *id, int level,
 }
 
 /**
- * debug_int_event() - writes debug entry to active debug area
+ * debug_int_event() - writes unsigned integer debug entry to active debug area
  *		       (if level <= actual debug level)
  *
  * @id:		handle for debug log
@@ -226,12 +169,12 @@ static inline debug_entry_t *debug_int_event(debug_info_t *id, int level,
 }
 
 /**
- * debug_long_event() - writes debug entry to active debug area
+ * debug_long_event() - writes unsigned long debug entry to active debug area
  *		       (if level <= actual debug level)
  *
  * @id:		handle for debug log
  * @level:	debug level
- * @tag:	integer value for debug entry
+ * @tag:	long integer value for debug entry
  *
  * Return:
  * - Address of written debug entry
@@ -248,7 +191,7 @@ static inline debug_entry_t *debug_long_event(debug_info_t *id, int level,
 }
 
 /**
- * debug_text_event() - writes debug entry in ascii format to active
+ * debug_text_event() - writes string debug entry in ascii format to active
  *			debug area (if level <= actual debug level)
  *
  * @id:		handle for debug log
@@ -306,9 +249,9 @@ __debug_sprintf_event(debug_info_t *id, int level, char *string, ...)
 })
 
 /**
- * debug_exception() - writes debug entry to active debug area
- *		       (if level <= actual debug level) and switches
- *		       to next debug area
+ * debug_exception() - writes binary debug entry to active debug area
+ *		       (if level <= actual debug level)
+ *		       and switches to next debug area
  *
  * @id:		handle for debug log
  * @level:	debug level
@@ -328,7 +271,7 @@ static inline debug_entry_t *debug_exception(debug_info_t *id, int level,
 }
 
 /**
- * debug_int_exception() - writes debug entry to active debug area
+ * debug_int_exception() - writes unsigned int debug entry to active debug area
  *			   (if level <= actual debug level)
  *			   and switches to next debug area
  *
@@ -351,13 +294,13 @@ static inline debug_entry_t *debug_int_exception(debug_info_t *id, int level,
 }
 
 /**
- * debug_long_exception() - writes debug entry to active debug area
+ * debug_long_exception() - writes long debug entry to active debug area
  *			   (if level <= actual debug level)
  *			   and switches to next debug area
  *
  * @id:		handle for debug log
  * @level:	debug level
- * @tag:	integer value for debug entry
+ * @tag:	long integer value for debug entry
  *
  * Return:
  * - Address of written debug entry
@@ -374,9 +317,9 @@ static inline debug_entry_t *debug_long_exception (debug_info_t *id, int level,
 }
 
 /**
- * debug_text_exception() - writes debug entry in ascii format to active
+ * debug_text_exception() - writes string debug entry in ascii format to active
  *			    debug area (if level <= actual debug level)
- *			    and switches to next debug
+ *			    and switches to next debug area
  * area
  *
  * @id:	handle for debug log
@@ -407,7 +350,7 @@ __debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
 /**
  * debug_sprintf_exception() - writes debug entry with format string and
  *			       varargs (longs) to active debug area
- *			       (if level $<=$ actual debug level)
+ *			       (if level <= actual debug level)
  *			       and switches to next debug area.
  *
  * @_id:	handle for debug log
@@ -435,33 +378,8 @@ __debug_sprintf_exception(debug_info_t *id, int level, char *string, ...)
 	__ret;								\
 })
 
-/**
- * debug_register_view() - registers new debug view and creates debugfs
- *			   dir entry
- *
- * @id:	handle for debug log
- * @view:	pointer to debug view struct
- *
- * Return:
- * -   0  : ok
- * -   < 0: Error
- */
 int debug_register_view(debug_info_t *id, struct debug_view *view);
 
-/**
- * debug_unregister_view()
- *
- * @id:	handle for debug log
- * @view:	pointer to debug view struct
- *
- * Return:
- * -   0  : ok
- * -   < 0: Error
- *
- *
- * unregisters debug view and removes debugfs dir entry
- */
-
 int debug_unregister_view(debug_info_t *id, struct debug_view *view);
 
 /*