Re: [RFC] Docbook: allow warning on unused documentation

[Randy Dunlap <rdunlap@xenotime.net>]

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?

> 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(-)
> 
> --- wireless-testing.orig/Documentation/kernel-doc-nano-HOWTO.txt	2010-08-18 14:54:25.000000000 +0200
> +++ wireless-testing/Documentation/kernel-doc-nano-HOWTO.txt	2010-08-18 14:57:12.000000000 +0200
> @@ -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.
>  */ <twaugh@redhat.com>
> --- wireless-testing.orig/scripts/basic/docproc.c	2010-08-18 14:54:26.000000000 +0200
> +++ wireless-testing/scripts/basic/docproc.c	2010-08-18 14:56:27.000000000 +0200
> @@ -34,12 +34,14 @@
>   *
>   */
>  
> +#define _GNU_SOURCE

Can you explain why that is needed?  (curious)

>  #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>

> @@ -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??

> +	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 ***