Skip to contentSkip to conversation

doc-guide: kernel-doc: add comment about formatting verification

PATCH In review Mike Rapoport 2 participants 2 messages Feb 20, 2018 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc-guide: kernel-doc: add comment about formatting verification

Currently there is no automated checking for kernel-doc comments except running 'kernel-doc -v -none <filename>'. Mention the possibility to run kernel-doc to verify formatting of the comments in the kernel-doc guide.

---
 Documentation/doc-guide/kernel-doc.rst | 6 ++++++
 1 file changed, 6 insertions(+)
Documentation/doc-guide/kernel-doc.rst +6 -0
index c6c3297..bb5ed6d 100644
@@ -44,6 +44,12 @@ that somebody changing the code will also change the documentation. The
 overview kernel-doc comments may be placed anywhere at the top indentation
 level.
 
+Running the ``kernel-doc`` tool with increased verbosity and without actual
+output generation may be used to verify proper formating of the
+documentation comments. For example::
+
+	scripts/kernel-doc -v -none drivers/foo/bar.c
+
 Function documentation
 ----------------------
 
Signature · 1 line
2.7.4
#1 lore raw

Documentation/doc-guide/kernel-doc.rst that somebody changing the code will also change the documentation. The · line 48

Quoted 4 lines · Mike Rapoport

level.

Documentation/doc-guide/kernel-doc.rst +2 -0
+Running the ``kernel-doc`` tool with increased verbosity and without actual
+output generation may be used to verify proper formating of the

"formatting"

Documentation/doc-guide/kernel-doc.rst that somebody changing the code will also change the documentation. The · line 54

Quoted 6 lines
Documentation/doc-guide/kernel-doc.rst +4 -0
+documentation comments. For example::
+
+	scripts/kernel-doc -v -none drivers/foo/bar.c
+
 Function documentation
 ----------------------

And that's not exactly true. "make W=1" will run that exact command. For example:

$ make W=1 net/ipv4/
(...)
  CC      net/ipv4/tcp_input.o
net/ipv4/tcp_input.c:4279: warning: Excess function parameter 'dest' description in 'tcp_try_coalesce'
  CC      net/ipv4/tcp_output.o
net/ipv4/tcp_output.c:3177: warning: Function parameter or member 'sk' not described in 'tcp_make_synack'
(...)

perhaps sneak that information in there somewhere.

Also it'll prompt people to run with W=1, so perhaps they'll fix their more-easily-fixed warnings ;-)