Skip to contentSkip to conversation

docbook: warn on unused doc entries

PATCH New Randy Dunlap 1 participant 1 message Sep 11, 2010

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docbook: warn on unused doc entries

From: Johannes Berg <[email protected]>

When you don't use !E or !I but only !F, then it's very easy to miss including some functions, structs etc. in documentation. To help finding which ones were missed, allow printing out the unused ones as warnings.

For example, using this on mac80211 yields a lot of warnings like this:

Warning: didn't use docs for DOC: mac80211 workqueue
Warning: didn't use docs for ieee80211_max_queues
Warning: didn't use docs for ieee80211_bss_change
Warning: didn't use docs for ieee80211_bss_conf

when generating the documentation for it.

---
v2: - fix comment
- use !C instead of !A

 Documentation/kernel-doc-nano-HOWTO.txt |    5 
 scripts/basic/docproc.c                 |  129 +++++++++++++++++++++-
 scripts/kernel-doc                      |   52 ++++++++
 3 files changed, 183 insertions(+), 3 deletions(-)
Documentation/kernel-doc-nano-HOWTO.txt +5 -0
@@ -345,5 +345,10 @@ documentation, in <filename>, for the fu
 section titled <section title> from <filename>.
 Spaces are allowed in <section title>; do not quote the <section title>.
 
+!C<filename> is replaced by nothing, but makes the tools check that
+all DOC: sections and documented functions, symbols, etc. are used.
+This makes sense to use when you use !F/!P only and want to verify
+that all documentation is included.
+
 Tim.
 */ <[email protected]>
scripts/basic/docproc.c +128 -1

221 lines not on this page · raw message

scripts/kernel-doc +50 -2

83 lines not on this page · raw message