lkml.org 
[lkml]   [2010]   [Aug]   [26]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [RFC] Docbook: allow warning on unused documentation
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 ***

\
 
 \ /
  Last update: 2010-08-26 18:39    [from the cache]
©2003-2011 Jasper Spaans