[media] doc-rst: Fix conversion for v4l2 core functions

The conversion from DocBook lead into some conversion issues,
basically due to the lack of proper support at kernel-doc.

So, address them:

- Now, the C files with the exported symbols also need to be
  added. So, all headers need to be included twice: one to
  get the structs/enums/.. and another one for the functions;

- Notes should use the ReST tag, as kernel-doc doesn't
  recognizes it anymore;

- Identation needs to be fixed, as ReST uses it to identify
  when a format "tag" ends.

- kernel-doc doesn't escape things like *pointer, so we
  need to manually add a escape char before it.

- On some cases, kernel-doc conversion requires violating
  the 80-cols, as otherwise it won't properly parse the
  source code.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

1 files changed, 18 insertions, 12 deletions

diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index 88e3ab496e8f..01cdd5bf90c8 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -86,11 +86,17 @@ struct vb2_threadio_data;
  * @mmap:	setup a userspace mapping for a given memory buffer under
  *		the provided virtual memory region.
  *
- * Required ops for USERPTR types: get_userptr, put_userptr.
- * Required ops for MMAP types: alloc, put, num_users, mmap.
- * Required ops for read/write access types: alloc, put, num_users, vaddr.
- * Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf,
- *				  unmap_dmabuf.
+ * Those operations are used by the videobuf2 core to implement the memory
+ * handling/memory allocators for each type of supported streaming I/O method.
+ *
+ * .. note::
+ *    #) Required ops for USERPTR types: get_userptr, put_userptr.
+ *
+ *    #) Required ops for MMAP types: alloc, put, num_users, mmap.
+ *
+ *    #) Required ops for read/write access types: alloc, put, num_users, vaddr.
+ *
+ *    #) Required ops for DMABUF types: attach_dmabuf, detach_dmabuf, map_dmabuf, unmap_dmabuf.
  */
 struct vb2_mem_ops {
 	void		*(*alloc)(void *alloc_ctx, unsigned long size,
@@ -279,19 +285,19 @@ struct vb2_buffer {
  *			second time with the actually allocated number of
  *			buffers to verify if that is OK.
  *			The driver should return the required number of buffers
- *			in *num_buffers, the required number of planes per
- *			buffer in *num_planes, the size of each plane should be
+ *			in \*num_buffers, the required number of planes per
+ *			buffer in \*num_planes, the size of each plane should be
  *			set in the sizes[] array and optional per-plane
  *			allocator specific context in the alloc_ctxs[] array.
- *			When called from VIDIOC_REQBUFS, *num_planes == 0, the
+ *			When called from VIDIOC_REQBUFS, \*num_planes == 0, the
  *			driver has to use the currently configured format to
- *			determine the plane sizes and *num_buffers is the total
+ *			determine the plane sizes and \*num_buffers is the total
  *			number of buffers that are being allocated. When called
- *			from VIDIOC_CREATE_BUFS, *num_planes != 0 and it
+ *			from VIDIOC_CREATE_BUFS, \*num_planes != 0 and it
  *			describes the requested number of planes and sizes[]
  *			contains the requested plane sizes. If either
- *			*num_planes or the requested sizes are invalid callback
- *			must return -EINVAL. In this case *num_buffers are
+ *			\*num_planes or the requested sizes are invalid callback
+ *			must return -EINVAL. In this case \*num_buffers are
  *			being allocated additionally to q->num_buffers.
  * @wait_prepare:	release any locks taken while calling vb2 functions;
  *			it is called before an ioctl needs to wait for a new