How to fix DocBook parsers for private fields inside #ifdefs

[Mauro Carvalho Chehab <mchehab@osg.samsung.com>]

Hi Jon,


I'm trying to cleanup some warnings when creating docbooks for a struct located
at include/media/videobuf2-core.h. 

This is the struct:

struct vb2_buffer {
        struct vb2_queue        *vb2_queue;
        unsigned int            index;
        unsigned int            type;
        unsigned int            memory;
        unsigned int            num_planes;
        struct vb2_plane        planes[VIDEO_MAX_PLANES];

        /* Private: internal use only */
        enum vb2_buffer_state   state;

        struct list_head        queued_entry;
        struct list_head        done_entry;
#ifdef CONFIG_VIDEO_ADV_DEBUG
        /*
         * Counters for how often these buffer-related ops are
         * called. Used to check for unbalanced ops.
         */
        u32             cnt_mem_alloc;
...
#endif
}

The data at the ifdef are used only for debugging purposes during driver
development or driver testing and should not be used in production.

They're all after a private comment:
	/* Private: internal use only */

So, according with Documentation/kernel-doc-nano-HOWTO.txt, they shold
have been ignored.

Still, the scripts produce warnings for them:

$ make cleandocs
$ make DOCBOOKS=device-drivers.xml htmldocs 2>&1|grep /media/

.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_alloc'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_put'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_get_dmabuf'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_get_userptr'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_put_userptr'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_prepare'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_finish'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_attach_dmabuf'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_detach_dmabuf'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_map_dmabuf'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_unmap_dmabuf'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_vaddr'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_cookie'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_num_users'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_mem_mmap'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_init'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_prepare'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_finish'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_cleanup'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_queue'
.//include/media/videobuf2-core.h:254: warning: No description found for parameter 'cnt_buf_done'

I tried to add another private: after the #ifdef, but it still produces
those warnings.

Any idea about how to fix it?

Thanks!
Mauro