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    [W:0.038 / U:64.944 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site