How to fix DocBook parsers for private fields inside #ifdefs
diff mbox

Message ID 20151005090348.7937fa4a@recife.lan
State New
Headers show

Commit Message

Mauro Carvalho Chehab Oct. 5, 2015, 12:03 p.m. UTC
Em Mon, 5 Oct 2015 04:56:35 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Thu, 1 Oct 2015 14:21:07 -0300
> Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
> 
> > 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:
> 
> Sorry, I've been away from the keyboard for a few days and am only now
> catching up.
> 
> The problem is that kernel-doc is dumb...the test is case-sensitive, so
> it needs to be "private:", not "Private:".  I'm sure there's a magic perl
> regex parameter to make the test case-insensitive; when I get a chance
> I'll figure it out and put it in there.

Ah, that makes sense. Adding an "i" to the end of the regex expression
should make it case-insensitive:

-       $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
-       $members =~ s/\/\*\s*private:.*//gos;
+       $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
+       $members =~ s/\/\*\s*private:.*//gosi;

Patch enclosed. Yet, I guess nobody would try to use PRIVATE: So, 
another alternative would be to do, instead:

-	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
-	$members =~ s/\/\*\s*private:.*//gos;
+	$members =~ s/\/\*\s*[Pp]rivate:.*?\/\*\s*public:.*?\*\///gos;
+	$members =~ s/\/\*\s*[Pp]rivate:.*//gos;

Whatever works best for you.

> (Of course, once you fix that glitch, you'll get gripes about the fields
> that are marked private but documented anyway.  Like I said, kernel-doc
> is dumb.)

Yeah, now I'm getting those warnings:

.//include/media/videobuf2-core.h:254: warning: Excess struct/union/enum/typedef member 'state' description in 'vb2_buffer'
.//include/media/videobuf2-core.h:254: warning: Excess struct/union/enum/typedef member 'queued_entry' description in 'vb2_buffer'
.//include/media/videobuf2-core.h:254: warning: Excess struct/union/enum/typedef member 'done_entry' description in 'vb2_buffer'

I'll fix that.

-

DocBook: Fix kernel-doc to be case-insensitive for private:

On some places, people could use Private: to tag the private fields
of an struct. So, be case-insensitive when parsing "private:"
meta-tag.

Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>


--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Comments

kbuild test robot Oct. 5, 2015, 12:35 p.m. UTC | #1
Hi Mauro,

[auto build test WARNING on v4.3-rc4 -- if it's inappropriate base, please ignore]

reproduce: make htmldocs

All warnings (new ones prefixed by >>):

   include/linux/init.h:1: warning: no structured comments found
   kernel/sys.c:1: warning: no structured comments found
   drivers/dma-buf/seqno-fence.c:1: warning: no structured comments found
   drivers/dma-buf/reservation.c:1: warning: no structured comments found
   include/linux/reservation.h:1: warning: no structured comments found
   include/media/v4l2-dv-timings.h:29: warning: cannot understand function prototype: 'const struct v4l2_dv_timings v4l2_dv_timings_presets[]; '
   include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'frame_height'
   include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'hfreq'
   include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'vsync'
   include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'active_width'
   include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'polarities'
   include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'interlaced'
   include/media/v4l2-dv-timings.h:147: warning: No description found for parameter 'fmt'
   include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'frame_height'
   include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'hfreq'
   include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'vsync'
   include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'polarities'
   include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'interlaced'
   include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'aspect'
   include/media/v4l2-dv-timings.h:171: warning: No description found for parameter 'fmt'
   include/media/v4l2-dv-timings.h:184: warning: No description found for parameter 'hor_landscape'
   include/media/v4l2-dv-timings.h:184: warning: No description found for parameter 'vert_portrait'
   include/media/videobuf2-core.h:112: warning: No description found for parameter 'get_dmabuf'
>> include/media/videobuf2-core.h:233: warning: Excess struct/union/enum/typedef member 'state' description in 'vb2_buffer'
>> include/media/videobuf2-core.h:233: warning: Excess struct/union/enum/typedef member 'queued_entry' description in 'vb2_buffer'
>> include/media/videobuf2-core.h:233: warning: Excess struct/union/enum/typedef member 'done_entry' description in 'vb2_buffer'
>> include/media/videobuf2-core.h:233: warning: Excess struct/union/enum/typedef member 'planes' description in 'vb2_buffer'
   drivers/media/dvb-core/dvbdev.h:199: warning: Excess function parameter 'device' description in 'dvb_register_device'
   drivers/media/dvb-core/dvbdev.h:199: warning: Excess function parameter 'adapter_nums' description in 'dvb_register_device'
   include/linux/hsi/hsi.h:150: warning: Excess struct/union/enum/typedef member 'e_handler' description in 'hsi_client'
   include/linux/hsi/hsi.h:150: warning: Excess struct/union/enum/typedef member 'pclaimed' description in 'hsi_client'
   include/linux/hsi/hsi.h:150: warning: Excess struct/union/enum/typedef member 'nb' description in 'hsi_client'

vim +233 include/media/videobuf2-core.h

e23ccc0a Pawel Osciak          2010-10-11  106  	void		*(*vaddr)(void *buf_priv);
e23ccc0a Pawel Osciak          2010-10-11  107  	void		*(*cookie)(void *buf_priv);
e23ccc0a Pawel Osciak          2010-10-11  108  
e23ccc0a Pawel Osciak          2010-10-11  109  	unsigned int	(*num_users)(void *buf_priv);
e23ccc0a Pawel Osciak          2010-10-11  110  
e23ccc0a Pawel Osciak          2010-10-11  111  	int		(*mmap)(void *buf_priv, struct vm_area_struct *vma);
e23ccc0a Pawel Osciak          2010-10-11 @112  };
e23ccc0a Pawel Osciak          2010-10-11  113  
e23ccc0a Pawel Osciak          2010-10-11  114  struct vb2_plane {
e23ccc0a Pawel Osciak          2010-10-11  115  	void			*mem_priv;
c5384048 Sumit Semwal          2012-06-14  116  	struct dma_buf		*dbuf;
c5384048 Sumit Semwal          2012-06-14  117  	unsigned int		dbuf_mapped;
e23ccc0a Pawel Osciak          2010-10-11  118  };
e23ccc0a Pawel Osciak          2010-10-11  119  
e23ccc0a Pawel Osciak          2010-10-11  120  /**
e23ccc0a Pawel Osciak          2010-10-11  121   * enum vb2_io_modes - queue access methods
e23ccc0a Pawel Osciak          2010-10-11  122   * @VB2_MMAP:		driver supports MMAP with streaming API
e23ccc0a Pawel Osciak          2010-10-11  123   * @VB2_USERPTR:	driver supports USERPTR with streaming API
e23ccc0a Pawel Osciak          2010-10-11  124   * @VB2_READ:		driver supports read() style access
e23ccc0a Pawel Osciak          2010-10-11  125   * @VB2_WRITE:		driver supports write() style access
c5384048 Sumit Semwal          2012-06-14  126   * @VB2_DMABUF:		driver supports DMABUF with streaming API
e23ccc0a Pawel Osciak          2010-10-11  127   */
e23ccc0a Pawel Osciak          2010-10-11  128  enum vb2_io_modes {
e23ccc0a Pawel Osciak          2010-10-11  129  	VB2_MMAP	= (1 << 0),
e23ccc0a Pawel Osciak          2010-10-11  130  	VB2_USERPTR	= (1 << 1),
e23ccc0a Pawel Osciak          2010-10-11  131  	VB2_READ	= (1 << 2),
e23ccc0a Pawel Osciak          2010-10-11  132  	VB2_WRITE	= (1 << 3),
c5384048 Sumit Semwal          2012-06-14  133  	VB2_DMABUF	= (1 << 4),
e23ccc0a Pawel Osciak          2010-10-11  134  };
e23ccc0a Pawel Osciak          2010-10-11  135  
e23ccc0a Pawel Osciak          2010-10-11  136  /**
e23ccc0a Pawel Osciak          2010-10-11  137   * enum vb2_buffer_state - current video buffer state
e23ccc0a Pawel Osciak          2010-10-11  138   * @VB2_BUF_STATE_DEQUEUED:	buffer under userspace control
b18a8ff2 Hans Verkuil          2013-12-13  139   * @VB2_BUF_STATE_PREPARING:	buffer is being prepared in videobuf
ebc087d0 Guennadi Liakhovetski 2011-08-31  140   * @VB2_BUF_STATE_PREPARED:	buffer prepared in videobuf and by the driver
e23ccc0a Pawel Osciak          2010-10-11  141   * @VB2_BUF_STATE_QUEUED:	buffer queued in videobuf, but not in driver
6d058c56 Sakari Ailus          2015-07-03  142   * @VB2_BUF_STATE_REQUEUEING:	re-queue a buffer to the driver
e23ccc0a Pawel Osciak          2010-10-11  143   * @VB2_BUF_STATE_ACTIVE:	buffer queued in driver and possibly used
e23ccc0a Pawel Osciak          2010-10-11  144   *				in a hardware operation
e23ccc0a Pawel Osciak          2010-10-11  145   * @VB2_BUF_STATE_DONE:		buffer returned from driver to videobuf, but
e23ccc0a Pawel Osciak          2010-10-11  146   *				not yet dequeued to userspace
e23ccc0a Pawel Osciak          2010-10-11  147   * @VB2_BUF_STATE_ERROR:	same as above, but the operation on the buffer
e23ccc0a Pawel Osciak          2010-10-11  148   *				has ended with an error, which will be reported
e23ccc0a Pawel Osciak          2010-10-11  149   *				to the userspace when it is dequeued
e23ccc0a Pawel Osciak          2010-10-11  150   */
e23ccc0a Pawel Osciak          2010-10-11  151  enum vb2_buffer_state {
e23ccc0a Pawel Osciak          2010-10-11  152  	VB2_BUF_STATE_DEQUEUED,
b18a8ff2 Hans Verkuil          2013-12-13  153  	VB2_BUF_STATE_PREPARING,
ebc087d0 Guennadi Liakhovetski 2011-08-31  154  	VB2_BUF_STATE_PREPARED,
e23ccc0a Pawel Osciak          2010-10-11  155  	VB2_BUF_STATE_QUEUED,
6d058c56 Sakari Ailus          2015-07-03  156  	VB2_BUF_STATE_REQUEUEING,
e23ccc0a Pawel Osciak          2010-10-11  157  	VB2_BUF_STATE_ACTIVE,
e23ccc0a Pawel Osciak          2010-10-11  158  	VB2_BUF_STATE_DONE,
e23ccc0a Pawel Osciak          2010-10-11  159  	VB2_BUF_STATE_ERROR,
e23ccc0a Pawel Osciak          2010-10-11  160  };
e23ccc0a Pawel Osciak          2010-10-11  161  
e23ccc0a Pawel Osciak          2010-10-11  162  struct vb2_queue;
e23ccc0a Pawel Osciak          2010-10-11  163  
e23ccc0a Pawel Osciak          2010-10-11  164  /**
e23ccc0a Pawel Osciak          2010-10-11  165   * struct vb2_buffer - represents a video buffer
e23ccc0a Pawel Osciak          2010-10-11  166   * @v4l2_buf:		struct v4l2_buffer associated with this buffer; can
e23ccc0a Pawel Osciak          2010-10-11  167   *			be read by the driver and relevant entries can be
e23ccc0a Pawel Osciak          2010-10-11  168   *			changed by the driver in case of CAPTURE types
e23ccc0a Pawel Osciak          2010-10-11  169   *			(such as timestamp)
e23ccc0a Pawel Osciak          2010-10-11  170   * @v4l2_planes:	struct v4l2_planes associated with this buffer; can
e23ccc0a Pawel Osciak          2010-10-11  171   *			be read by the driver and relevant entries can be
e23ccc0a Pawel Osciak          2010-10-11  172   *			changed by the driver in case of CAPTURE types
e23ccc0a Pawel Osciak          2010-10-11  173   *			(such as bytesused); NOTE that even for single-planar
e23ccc0a Pawel Osciak          2010-10-11  174   *			types, the v4l2_planes[0] struct should be used
e23ccc0a Pawel Osciak          2010-10-11  175   *			instead of v4l2_buf for filling bytesused - drivers
e23ccc0a Pawel Osciak          2010-10-11  176   *			should use the vb2_set_plane_payload() function for that
e23ccc0a Pawel Osciak          2010-10-11  177   * @vb2_queue:		the queue to which this driver belongs
e23ccc0a Pawel Osciak          2010-10-11  178   * @num_planes:		number of planes in the buffer
e23ccc0a Pawel Osciak          2010-10-11  179   *			on an internal driver queue
e23ccc0a Pawel Osciak          2010-10-11  180   * @state:		current buffer state; do not change
e23ccc0a Pawel Osciak          2010-10-11  181   * @queued_entry:	entry on the queued buffers list, which holds all
e23ccc0a Pawel Osciak          2010-10-11  182   *			buffers queued from userspace
e23ccc0a Pawel Osciak          2010-10-11  183   * @done_entry:		entry on the list that stores all buffers ready to
e23ccc0a Pawel Osciak          2010-10-11  184   *			be dequeued to userspace
e23ccc0a Pawel Osciak          2010-10-11  185   * @planes:		private per-plane information; do not change
e23ccc0a Pawel Osciak          2010-10-11  186   */
e23ccc0a Pawel Osciak          2010-10-11  187  struct vb2_buffer {
e23ccc0a Pawel Osciak          2010-10-11  188  	struct v4l2_buffer	v4l2_buf;
e23ccc0a Pawel Osciak          2010-10-11  189  	struct v4l2_plane	v4l2_planes[VIDEO_MAX_PLANES];
e23ccc0a Pawel Osciak          2010-10-11  190  
e23ccc0a Pawel Osciak          2010-10-11  191  	struct vb2_queue	*vb2_queue;
e23ccc0a Pawel Osciak          2010-10-11  192  
e23ccc0a Pawel Osciak          2010-10-11  193  	unsigned int		num_planes;
e23ccc0a Pawel Osciak          2010-10-11  194  
e23ccc0a Pawel Osciak          2010-10-11  195  /* Private: internal use only */
e23ccc0a Pawel Osciak          2010-10-11  196  	enum vb2_buffer_state	state;
e23ccc0a Pawel Osciak          2010-10-11  197  
e23ccc0a Pawel Osciak          2010-10-11  198  	struct list_head	queued_entry;
e23ccc0a Pawel Osciak          2010-10-11  199  	struct list_head	done_entry;
e23ccc0a Pawel Osciak          2010-10-11  200  
e23ccc0a Pawel Osciak          2010-10-11  201  	struct vb2_plane	planes[VIDEO_MAX_PLANES];
b5b4541e Hans Verkuil          2014-01-29  202  
b5b4541e Hans Verkuil          2014-01-29  203  #ifdef CONFIG_VIDEO_ADV_DEBUG
b5b4541e Hans Verkuil          2014-01-29  204  	/*
b5b4541e Hans Verkuil          2014-01-29  205  	 * Counters for how often these buffer-related ops are
b5b4541e Hans Verkuil          2014-01-29  206  	 * called. Used to check for unbalanced ops.
b5b4541e Hans Verkuil          2014-01-29  207  	 */
b5b4541e Hans Verkuil          2014-01-29  208  	u32		cnt_mem_alloc;
b5b4541e Hans Verkuil          2014-01-29  209  	u32		cnt_mem_put;
b5b4541e Hans Verkuil          2014-01-29  210  	u32		cnt_mem_get_dmabuf;
b5b4541e Hans Verkuil          2014-01-29  211  	u32		cnt_mem_get_userptr;
b5b4541e Hans Verkuil          2014-01-29  212  	u32		cnt_mem_put_userptr;
b5b4541e Hans Verkuil          2014-01-29  213  	u32		cnt_mem_prepare;
b5b4541e Hans Verkuil          2014-01-29  214  	u32		cnt_mem_finish;
b5b4541e Hans Verkuil          2014-01-29  215  	u32		cnt_mem_attach_dmabuf;
b5b4541e Hans Verkuil          2014-01-29  216  	u32		cnt_mem_detach_dmabuf;
b5b4541e Hans Verkuil          2014-01-29  217  	u32		cnt_mem_map_dmabuf;
b5b4541e Hans Verkuil          2014-01-29  218  	u32		cnt_mem_unmap_dmabuf;
b5b4541e Hans Verkuil          2014-01-29  219  	u32		cnt_mem_vaddr;
b5b4541e Hans Verkuil          2014-01-29  220  	u32		cnt_mem_cookie;
b5b4541e Hans Verkuil          2014-01-29  221  	u32		cnt_mem_num_users;
b5b4541e Hans Verkuil          2014-01-29  222  	u32		cnt_mem_mmap;
b5b4541e Hans Verkuil          2014-01-29  223  
b5b4541e Hans Verkuil          2014-01-29  224  	u32		cnt_buf_init;
b5b4541e Hans Verkuil          2014-01-29  225  	u32		cnt_buf_prepare;
b5b4541e Hans Verkuil          2014-01-29  226  	u32		cnt_buf_finish;
b5b4541e Hans Verkuil          2014-01-29  227  	u32		cnt_buf_cleanup;
b5b4541e Hans Verkuil          2014-01-29  228  	u32		cnt_buf_queue;
b5b4541e Hans Verkuil          2014-01-29  229  
b5b4541e Hans Verkuil          2014-01-29  230  	/* This counts the number of calls to vb2_buffer_done() */
b5b4541e Hans Verkuil          2014-01-29  231  	u32		cnt_buf_done;
b5b4541e Hans Verkuil          2014-01-29  232  #endif
e23ccc0a Pawel Osciak          2010-10-11 @233  };
e23ccc0a Pawel Osciak          2010-10-11  234  
e23ccc0a Pawel Osciak          2010-10-11  235  /**
e23ccc0a Pawel Osciak          2010-10-11  236   * struct vb2_ops - driver-specific callbacks

:::::: The code at line 233 was first introduced by commit
:::::: e23ccc0ad9258634e6d52cedf473b35dc34416c7 [media] v4l: add videobuf2 Video for Linux 2 driver framework

:::::: TO: Pawel Osciak <p.osciak@samsung.com>
:::::: CC: Mauro Carvalho Chehab <mchehab@redhat.com>

---
0-DAY kernel test infrastructure                Open Source Technology Center
https://lists.01.org/pipermail/kbuild-all                   Intel Corporation
Jonathan Corbet Oct. 11, 2015, 9:38 p.m. UTC | #2
On Mon, 5 Oct 2015 09:03:48 -0300
Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:

> Patch enclosed.

...and applied, thanks!

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Patch
diff mbox

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9a08fb5c1af6..702c6ac1350e 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1791,8 +1791,8 @@  sub dump_struct($$) {
 	$nested = $1;
 
 	# ignore members marked private:
-	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
-	$members =~ s/\/\*\s*private:.*//gos;
+	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
+	$members =~ s/\/\*\s*private:.*//gosi;
 	# strip comments:
 	$members =~ s/\/\*.*?\*\///gos;
 	$nested =~ s/\/\*.*?\*\///gos;