Skip to contentSkip to conversation

Docbook: allow warning on unused documentation

RFC In review Johannes Berg 2 participants 7 messages Aug 18, 2010 – Aug 26, 2010

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

RFC 1/1 Docbook: allow warning on unused documentation

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.

---
 Documentation/kernel-doc-nano-HOWTO.txt |    5 +
 scripts/basic/docproc.c                 |  130 +++++++++++++++++++++++++++++++-
 scripts/kernel-doc                      |   52 ++++++++++++
 3 files changed, 184 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>.
 
+!A<filename> is replaced by nothing, but makes the tools verify 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 +129 -1

222 lines not on this page · raw message

scripts/kernel-doc +50 -2

83 lines not on this page · raw message

#1 lore raw
Quoted 5 lines · On Wed, 18 Aug 2010 15:09:27 +0200 Johannes Berg wrote:

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.

How do I test this? Do I need to add !A to some source file?

Quoted 32 lines

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.

---
 Documentation/kernel-doc-nano-HOWTO.txt |    5 +
 scripts/basic/docproc.c                 |  130 +++++++++++++++++++++++++++++++-
 scripts/kernel-doc                      |   52 ++++++++++++
 3 files changed, 184 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>.
 
+!A<filename> is replaced by nothing, but makes the tools verify 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 line 37

Quoted 4 lines
scripts/basic/docproc.c +1 -0
@@ -34,12 +34,14 @@
  *
  */
 
+#define _GNU_SOURCE

Can you explain why that is needed? (curious)

Quoted 11 lines
scripts/basic/docproc.c +1 -0
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <ctype.h>
 #include <unistd.h>
 #include <limits.h>
+#include <errno.h>
 #include <sys/types.h>
 #include <sys/wait.h>
 

scripts/basic/docproc.c static void docsect(char *filename, char · line 351

Quoted 6 lines
scripts/basic/docproc.c +3 -0
@@ -315,6 +346,85 @@ static void docsect(char *filename, char
 	exec_kernel_doc(vec);
 }
 
+static void find_all_symbols(char *filename)
+{
+	char *vec[4]; /* kerneldoc -docbook -function "section" file NULL */

incorrect comment??

scripts/basic/docproc.c static void docsect(char *filename, char · line 362

Quoted 11 lines
scripts/basic/docproc.c +11 -0
+	pid_t pid;
+	int ret, i, count, start;
+	char real_filename[PATH_MAX + 1];
+	int pipefd[2];
+	char *data, *str;
+	size_t data_len = 0;
+
+	vec[0] = KERNELDOC;
+	vec[1] = LIST;
+	vec[2] = filename;
+	vec[3] = NULL;

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

#2 lore raw
Quoted 9 lines · Randy Dunlap
Quoted 5 lines · On Wed, 18 Aug 2010 15:09:27 +0200 Johannes Berg wrote:

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.

How do I test this? Do I need to add !A to some source file?

Yeah, like to Documentation/DocBook/mac80211.tmpl you could add !Ainclude/net/mac80211.h

Quoted 3 lines
Quoted 1 line

+#define _GNU_SOURCE

Can you explain why that is needed? (curious)

Yeah, I used asprintf somewhere.

Quoted 5 lines

scripts/basic/docproc.c static void docsect(char *filename, char · line 351

Quoted 3 lines
scripts/basic/docproc.c +3 -0
+static void find_all_symbols(char *filename)
+{
+	char *vec[4]; /* kerneldoc -docbook -function "section" file NULL */

incorrect comment??

Oops, yes:

Quoted 4 lines

scripts/basic/docproc.c static void docsect(char *filename, char · line 362

Quoted 4 lines
scripts/basic/docproc.c +4 -0
+	vec[0] = KERNELDOC;
+	vec[1] = LIST;
+	vec[2] = filename;
+	vec[3] = NULL;

johannes

#3 lore raw
Quoted 9 lines · On Thu, 26 Aug 2010 18:51:16 +0200 Johannes Berg wrote:
Quoted 8 lines · Randy Dunlap
Quoted 5 lines · On Wed, 18 Aug 2010 15:09:27 +0200 Johannes Berg wrote:

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.

Quoted 4 lines
Quoted 1 line

How do I test this? Do I need to add !A to some source file?

Yeah, like to Documentation/DocBook/mac80211.tmpl you could add !Ainclude/net/mac80211.h

Yes, I see. That output looks useful.

How about using !C (for "check") instead of !A ?

Quoted 5 lines
Quoted 3 lines
Quoted 1 line

+#define _GNU_SOURCE

Can you explain why that is needed? (curious)

Yeah, I used asprintf somewhere.

ack.

Quoted 6 lines
Quoted 5 lines

scripts/basic/docproc.c static void docsect(char *filename, char · line 351

Quoted 3 lines
scripts/basic/docproc.c +3 -0
+static void find_all_symbols(char *filename)
+{
+	char *vec[4]; /* kerneldoc -docbook -function "section" file NULL */

incorrect comment??

Quoted 6 lines

Oops, yes:

Quoted 4 lines

scripts/basic/docproc.c static void docsect(char *filename, char · line 362

Quoted 4 lines
scripts/basic/docproc.c +4 -0
+	vec[0] = KERNELDOC;
+	vec[1] = LIST;
+	vec[2] = filename;
+	vec[3] = NULL;

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

#4 lore raw
Quoted 8 lines · Randy Dunlap
Quoted 4 lines
Quoted 1 line

How do I test this? Do I need to add !A to some source file?

Yeah, like to Documentation/DocBook/mac80211.tmpl you could add !Ainclude/net/mac80211.h

Yes, I see. That output looks useful.

How about using !C (for "check") instead of !A ?

Sure, I can't say I care much, had "all" in mind when I came up with !A.

I fixed up the command, and can change that and resend.

johannes

#5 lore raw

PATCH 1/1 Docbook: allow warning on unused documentation

In reply to Randy Dunlap

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

Applied
#6 lore raw
Quoted 19 lines · On Thu, 26 Aug 2010 19:43:14 +0200 Johannes Berg wrote:

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.

Quoted 8 lines

---
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(-)

Applied, thanks.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***