[PATCH] printk/documentation: Update printk()/_printk() documentation

[Petr Mladek]

The commit 337015573718b161 ("printk: Userspace format indexing support")
caused the following warning when building htmldocs:

kernel/printk/printk.c:1: warning: 'printk' not found

The problem is that printk() became a macro that is defined
in include/linux/printk.h instead of kernel/printk.c. The original
function was renamed to _printk().

Fixes: 337015573718b161 ("printk: Userspace format indexing support")
Reported-by: Stephen Rothwell <sfr@xxxxxxxxxxxxxxxx>
Signed-off-by: Petr Mladek <pmladek@xxxxxxxx>
Link: https://lore.kernel.org/r/YPbBfdz9srIpI+bb@xxxxxxxxxxxxxx
---
This should do the trick. I do not longer see the warning.

Documentation/core-api/printk-basics.rst |  6 +++---
 include/linux/printk.h                   | 12 ++++++++++++
 kernel/printk/printk.c                   |  3 ++-
 3 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/Documentation/core-api/printk-basics.rst b/Documentation/core-api/printk-basics.rst
index 965e4281eddd..3160a73c27b1 100644
--- a/Documentation/core-api/printk-basics.rst
+++ b/Documentation/core-api/printk-basics.rst
@@ -108,8 +108,8 @@ Function reference
 ==================
 
 .. kernel-doc:: kernel/printk/printk.c
-   :functions: printk
+   :functions: _printk
 
 .. kernel-doc:: include/linux/printk.h
-   :functions: pr_emerg pr_alert pr_crit pr_err pr_warn pr_notice pr_info
-      pr_fmt pr_debug pr_devel pr_cont
+   :functions: printk pr_emerg pr_alert pr_crit pr_err pr_warn
+	pr_notice pr_info pr_fmt pr_debug pr_devel pr_cont
diff --git a/include/linux/printk.h b/include/linux/printk.h
index 2651b82ed352..e0e3411db67b 100644
--- a/include/linux/printk.h
+++ b/include/linux/printk.h
@@ -431,6 +431,18 @@ struct pi_entry {
 	})
 
 
+/**
+ * printk - Print a message
+ * @fmt: format string
+ * @...: arguments for the format string
+ *
+ * This macro generates metadata for printk indexing and prints the message
+ * using _printk(). It uses pr_fmt() to generate the format string.
+ *
+ * The default log level is used when a particular one is not part of
+ * the message prefix. pr_<level>() macros are preferred because each
+ * caller should know the exact purpose of the message.
+ */
 #define printk(fmt, ...) printk_index_wrap(_printk, fmt, ##__VA_ARGS__)
 #define printk_deferred(fmt, ...)					\
 	printk_index_wrap(_printk_deferred, fmt, ##__VA_ARGS__)
diff --git a/kernel/printk/printk.c b/kernel/printk/printk.c
index 765f7af6ce56..2e5559175214 100644
--- a/kernel/printk/printk.c
+++ b/kernel/printk/printk.c
@@ -2187,7 +2187,8 @@ EXPORT_SYMBOL_GPL(vprintk_default);
  * _printk - print a kernel message
  * @fmt: format string
  *
- * This is _printk(). It can be called from any context. We want it to work.
+ * This is printk() implementation. It can be called from any context.
+ * We want it to work.
  *
  * If printk indexing is enabled, _printk() is called from printk_index_wrap.
  * Otherwise, printk is simply #defined to _printk.
-- 
2.26.2