Merge tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media

Pull media documentation updates from Mauro Carvalho Chehab:
 "This patch series does the conversion of all media documentation stuff
  to Restrutured Text markup format and add them to the
  Documentation/index.rst file.

  The media documentation was grouped into 4 books:

    - media uAPI
    - media kAPI
    - V4L driver-specific documentation
    - DVB driver-specific documentation

  It also contains several documentation improvements and one fixup
  patch for a core issue with cropcap.

  PS.  After this patch series, the media DocBook is deprecated and
  should be removed.  I'll add such patch on a future pull request"

* tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (322 commits)
  [media] cx23885-cardlist.rst: add a new card
  [media] doc-rst: add some needed escape codes
  [media] doc-rst: kapi: use :c:func: instead of :cpp:func
  doc-rst: kernel-doc: fix a change introduced by mistake
  [media] v4l2-ioctl.h add debug info for struct v4l2_ioctl_ops
  [media] dvb_ringbuffer.h: some documentation improvements
  [media] v4l2-ctrls.h: fully document the header file
  [media] doc-rst: Fix some typedef ugly warnings
  [media] doc-rst: reorganize the kAPI v4l2 chapters
  [media] rename v4l2-framework.rst to v4l2-intro.rst
  [media] move V4L2 clocks to a separate .rst file
  [media] v4l2-fh.rst: add cross references and markups
  [media] v4l2-fh.rst: add fh contents from v4l2-framework.rst
  [media] v4l2-fh.h: add documentation for it
  [media] v4l2-event.rst: add cross-references and markups
  [media] v4l2-event.h: document all functions
  [media] v4l2-event.rst: add text from v4l2-framework.rst
  [media] v4l2-framework.rst: remove videobuf quick chapter
  [media] v4l2-dev: add cross-references and improve markup
  [media] doc-rst: move v4l2-dev doc to a separate file
  ...

20 files changed, 1913 insertions, 806 deletions

diff --git a/include/media/lirc_dev.h b/include/media/lirc_dev.h
index 0ab59a571fee..cec7d35602d1 100644
--- a/include/media/lirc_dev.h
+++ b/include/media/lirc_dev.h
@@ -140,7 +140,7 @@ static inline unsigned int lirc_buffer_write(struct lirc_buffer *buf,
  *			second.
  *
  * @features:		lirc compatible hardware features, like LIRC_MODE_RAW,
- *			LIRC_CAN_*, as defined at include/media/lirc.h.
+ *			LIRC_CAN\_\*, as defined at include/media/lirc.h.
  *
  * @chunk_size:		Size of each FIFO buffer.
  *
diff --git a/include/media/media-device.h b/include/media/media-device.h
index f743ae2210ee..28195242386c 100644
--- a/include/media/media-device.h
+++ b/include/media/media-device.h
@@ -29,237 +29,6 @@
 #include <media/media-devnode.h>
 #include <media/media-entity.h>
 
-/**
- * DOC: Media Controller
- *
- * The media controller userspace API is documented in DocBook format in
- * Documentation/DocBook/media/v4l/media-controller.xml. This document focus
- * on the kernel-side implementation of the media framework.
- *
- * * Abstract media device model:
- *
- * Discovering a device internal topology, and configuring it at runtime, is one
- * of the goals of the media framework. To achieve this, hardware devices are
- * modelled as an oriented graph of building blocks called entities connected
- * through pads.
- *
- * An entity is a basic media hardware building block. It can correspond to
- * a large variety of logical blocks such as physical hardware devices
- * (CMOS sensor for instance), logical hardware devices (a building block
- * in a System-on-Chip image processing pipeline), DMA channels or physical
- * connectors.
- *
- * A pad is a connection endpoint through which an entity can interact with
- * other entities. Data (not restricted to video) produced by an entity
- * flows from the entity's output to one or more entity inputs. Pads should
- * not be confused with physical pins at chip boundaries.
- *
- * A link is a point-to-point oriented connection between two pads, either
- * on the same entity or on different entities. Data flows from a source
- * pad to a sink pad.
- *
- *
- * * Media device:
- *
- * A media device is represented by a struct &media_device instance, defined in
- * include/media/media-device.h. Allocation of the structure is handled by the
- * media device driver, usually by embedding the &media_device instance in a
- * larger driver-specific structure.
- *
- * Drivers register media device instances by calling
- *	__media_device_register() via the macro media_device_register()
- * and unregistered by calling
- *	media_device_unregister().
- *
- * * Entities, pads and links:
- *
- * - Entities
- *
- * Entities are represented by a struct &media_entity instance, defined in
- * include/media/media-entity.h. The structure is usually embedded into a
- * higher-level structure, such as a v4l2_subdev or video_device instance,
- * although drivers can allocate entities directly.
- *
- * Drivers initialize entity pads by calling
- *	media_entity_pads_init().
- *
- * Drivers register entities with a media device by calling
- *	media_device_register_entity()
- * and unregistred by calling
- *	media_device_unregister_entity().
- *
- * - Interfaces
- *
- * Interfaces are represented by a struct &media_interface instance, defined in
- * include/media/media-entity.h. Currently, only one type of interface is
- * defined: a device node. Such interfaces are represented by a struct
- * &media_intf_devnode.
- *
- * Drivers initialize and create device node interfaces by calling
- *	media_devnode_create()
- * and remove them by calling:
- *	media_devnode_remove().
- *
- * - Pads
- *
- * Pads are represented by a struct &media_pad instance, defined in
- * include/media/media-entity.h. Each entity stores its pads in a pads array
- * managed by the entity driver. Drivers usually embed the array in a
- * driver-specific structure.
- *
- * Pads are identified by their entity and their 0-based index in the pads
- * array.
- * Both information are stored in the &media_pad structure, making the
- * &media_pad pointer the canonical way to store and pass link references.
- *
- * Pads have flags that describe the pad capabilities and state.
- *
- *	%MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
- *	%MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
- *
- * NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
- * be set for each pad.
- *
- * - Links
- *
- * Links are represented by a struct &media_link instance, defined in
- * include/media/media-entity.h. There are two types of links:
- *
- * 1. pad to pad links:
- *
- * Associate two entities via their PADs. Each entity has a list that points
- * to all links originating at or targeting any of its pads.
- * A given link is thus stored twice, once in the source entity and once in
- * the target entity.
- *
- * Drivers create pad to pad links by calling:
- *	media_create_pad_link() and remove with media_entity_remove_links().
- *
- * 2. interface to entity links:
- *
- * Associate one interface to a Link.
- *
- * Drivers create interface to entity links by calling:
- *	media_create_intf_link() and remove with media_remove_intf_links().
- *
- * NOTE:
- *
- * Links can only be created after having both ends already created.
- *
- * Links have flags that describe the link capabilities and state. The
- * valid values are described at media_create_pad_link() and
- * media_create_intf_link().
- *
- * Graph traversal:
- *
- * The media framework provides APIs to iterate over entities in a graph.
- *
- * To iterate over all entities belonging to a media device, drivers can use
- * the media_device_for_each_entity macro, defined in
- * include/media/media-device.h.
- *
- * 	struct media_entity *entity;
- *
- * 	media_device_for_each_entity(entity, mdev) {
- * 		// entity will point to each entity in turn
- * 		...
- * 	}
- *
- * Drivers might also need to iterate over all entities in a graph that can be
- * reached only through enabled links starting at a given entity. The media
- * framework provides a depth-first graph traversal API for that purpose.
- *
- * Note that graphs with cycles (whether directed or undirected) are *NOT*
- * supported by the graph traversal API. To prevent infinite loops, the graph
- * traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
- * currently defined as 16.
- *
- * Drivers initiate a graph traversal by calling
- *	media_entity_graph_walk_start()
- *
- * The graph structure, provided by the caller, is initialized to start graph
- * traversal at the given entity.
- *
- * Drivers can then retrieve the next entity by calling
- *	media_entity_graph_walk_next()
- *
- * When the graph traversal is complete the function will return NULL.
- *
- * Graph traversal can be interrupted at any moment. No cleanup function call
- * is required and the graph structure can be freed normally.
- *
- * Helper functions can be used to find a link between two given pads, or a pad
- * connected to another pad through an enabled link
- *	media_entity_find_link() and media_entity_remote_pad()
- *
- * Use count and power handling:
- *
- * Due to the wide differences between drivers regarding power management
- * needs, the media controller does not implement power management. However,
- * the &media_entity structure includes a use_count field that media drivers
- * can use to track the number of users of every entity for power management
- * needs.
- *
- * The &media_entity.@use_count field is owned by media drivers and must not be
- * touched by entity drivers. Access to the field must be protected by the
- * &media_device.@graph_mutex lock.
- *
- * Links setup:
- *
- * Link properties can be modified at runtime by calling
- *	media_entity_setup_link()
- *
- * Pipelines and media streams:
- *
- * When starting streaming, drivers must notify all entities in the pipeline to
- * prevent link states from being modified during streaming by calling
- *	media_entity_pipeline_start().
- *
- * The function will mark all entities connected to the given entity through
- * enabled links, either directly or indirectly, as streaming.
- *
- * The &media_pipeline instance pointed to by the pipe argument will be stored
- * in every entity in the pipeline. Drivers should embed the &media_pipeline
- * structure in higher-level pipeline structures and can then access the
- * pipeline through the &media_entity pipe field.
- *
- * Calls to media_entity_pipeline_start() can be nested. The pipeline pointer
- * must be identical for all nested calls to the function.
- *
- * media_entity_pipeline_start() may return an error. In that case, it will
- * clean up any of the changes it did by itself.
- *
- * When stopping the stream, drivers must notify the entities with
- *	media_entity_pipeline_stop().
- *
- * If multiple calls to media_entity_pipeline_start() have been made the same
- * number of media_entity_pipeline_stop() calls are required to stop streaming.
- * The &media_entity pipe field is reset to NULL on the last nested stop call.
- *
- * Link configuration will fail with -%EBUSY by default if either end of the
- * link is a streaming entity. Links that can be modified while streaming must
- * be marked with the %MEDIA_LNK_FL_DYNAMIC flag.
- *
- * If other operations need to be disallowed on streaming entities (such as
- * changing entities configuration parameters) drivers can explicitly check the
- * media_entity stream_count field to find out if an entity is streaming. This
- * operation must be done with the media_device graph_mutex held.
- *
- * Link validation:
- *
- * Link validation is performed by media_entity_pipeline_start() for any
- * entity which has sink pads in the pipeline. The
- * &media_entity.@link_validate() callback is used for that purpose. In
- * @link_validate() callback, entity driver should check that the properties of
- * the source pad of the connected entity and its own sink pad match. It is up
- * to the type of the entity (and in the end, the properties of the hardware)
- * what matching actually means.
- *
- * Subsystems should facilitate link validation by providing subsystem specific
- * helper functions to provide easy access for commonly needed information, and
- * in the end provide a way to use driver-specific callbacks.
- */
-
 struct ida;
 struct device;
 
@@ -473,13 +242,11 @@ void media_device_cleanup(struct media_device *mdev);
  *    without breaking binary compatibility. The version major must be
  *    incremented when binary compatibility is broken.
  *
- * Notes:
+ * .. note::
  *
- * Upon successful registration a character device named media[0-9]+ is created.
- * The device major and minor numbers are dynamic. The model name is exported as
- * a sysfs attribute.
+ *    #) Upon successful registration a character device named media[0-9]+ is created. The device major and minor numbers are dynamic. The model name is exported as a sysfs attribute.
  *
- * Unregistering a media device that hasn't been registered is *NOT* safe.
+ *    #) Unregistering a media device that hasn't been registered is **NOT** safe.
  *
  * Return: returns zero on success or a negative error code.
  */
@@ -527,14 +294,16 @@ void media_device_unregister(struct media_device *mdev);
  *	This can be used to report the default audio and video devices or the
  *	default camera sensor.
  *
- * NOTE: Drivers should set the entity function before calling this function.
- * Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and
- * %MEDIA_ENT_F_UNKNOWN should not be used by the drivers.
+ * .. note::
+ *
+ *    Drivers should set the entity function before calling this function.
+ *    Please notice that the values %MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN and
+ *    %MEDIA_ENT_F_UNKNOWN should not be used by the drivers.
  */
 int __must_check media_device_register_entity(struct media_device *mdev,
 					      struct media_entity *entity);
 
-/*
+/**
  * media_device_unregister_entity() - unregisters a media entity.
  *
  * @entity:	pointer to struct &media_entity to be unregistered
@@ -548,8 +317,10 @@ int __must_check media_device_register_entity(struct media_device *mdev,
  * When a media device is unregistered, all its entities are unregistered
  * automatically. No manual entities unregistration is then required.
  *
- * Note: the media_entity instance itself must be freed explicitly by
- * the driver if required.
+ * .. note::
+ *
+ *    The media_entity instance itself must be freed explicitly by
+ *    the driver if required.
  */
 void media_device_unregister_entity(struct media_entity *entity);
 
diff --git a/include/media/media-entity.h b/include/media/media-entity.h
index cbb266f7f2b5..09b03c17784d 100644
--- a/include/media/media-entity.h
+++ b/include/media/media-entity.h
@@ -104,7 +104,7 @@ struct media_entity_graph {
 	int top;
 };
 
-/*
+/**
  * struct media_pipeline - Media pipeline related information
  *
  * @streaming_count:	Streaming start count - streaming stop count
@@ -180,8 +180,10 @@ struct media_pad {
  *			view. The media_entity_pipeline_start() function
  *			validates all links by calling this operation. Optional.
  *
- * Note: Those these callbacks are called with struct media_device.@graph_mutex
- * mutex held.
+ * .. note::
+ *
+ *    Those these callbacks are called with struct media_device.@graph_mutex
+ *    mutex held.
  */
 struct media_entity_operations {
 	int (*link_setup)(struct media_entity *entity,
@@ -538,7 +540,7 @@ static inline bool media_entity_enum_intersects(
  * @gobj:	Pointer to the graph object
  *
  * This routine initializes the embedded struct media_gobj inside a
- * media graph object. It is called automatically if media_*_create()
+ * media graph object. It is called automatically if media_*_create\(\)
  * calls are used. However, if the object (entity, link, pad, interface)
  * is embedded on some other object, this function should be called before
  * registering the object at the media controller.
@@ -602,19 +604,20 @@ static inline void media_entity_cleanup(struct media_entity *entity) {};
  * @flags:	Link flags, as defined in include/uapi/linux/media.h.
  *
  * Valid values for flags:
- * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be
- *	used to transfer media data. When two or more links target a sink pad,
- *	only one of them can be enabled at a time.
  *
- * A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't
- *	be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then
- *	%MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
- *	always enabled.
+ * - A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can
+ *   be used to transfer media data. When two or more links target a sink pad,
+ *   only one of them can be enabled at a time.
+ *
+ * - A %MEDIA_LNK_FL_IMMUTABLE flag indicates that the link enabled state can't
+ *   be modified at runtime. If %MEDIA_LNK_FL_IMMUTABLE is set, then
+ *   %MEDIA_LNK_FL_ENABLED must also be set since an immutable link is
+ *   always enabled.
  *
- * NOTE:
+ * .. note::
  *
- * Before calling this function, media_entity_pads_init() and
- * media_device_register_entity() should be called previously for both ends.
+ *    Before calling this function, media_entity_pads_init() and
+ *    media_device_register_entity() should be called previously for both ends.
  */
 __must_check int media_create_pad_link(struct media_entity *source,
 			u16 source_pad, struct media_entity *sink,
@@ -641,6 +644,7 @@ __must_check int media_create_pad_link(struct media_entity *source,
  *	and @sink are NULL.
  *
  * Valid values for flags:
+ *
  * A %MEDIA_LNK_FL_ENABLED flag indicates that the link is enabled and can be
  *	used to transfer media data. If multiple links are created and this
  *	flag is passed as an argument, only the first created link will have
@@ -677,8 +681,10 @@ void __media_entity_remove_links(struct media_entity *entity);
  *
  * @entity:	pointer to &media_entity
  *
- * Note: this is called automatically when an entity is unregistered via
- * media_device_register_entity().
+ * .. note::
+ *
+ *    This is called automatically when an entity is unregistered via
+ *    media_device_register_entity().
  */
 void media_entity_remove_links(struct media_entity *entity);
 
@@ -728,9 +734,11 @@ int __media_entity_setup_link(struct media_link *link, u32 flags);
  * being enabled, the link_setup operation must return -EBUSY and can't
  * implicitly disable the first enabled link.
  *
- * NOTE: the valid values of the flags for the link is the same as described
- * on media_create_pad_link(), for pad to pad links or the same as described
- * on media_create_intf_link(), for interface to entity links.
+ * .. note::
+ *
+ *    The valid values of the flags for the link is the same as described
+ *    on media_create_pad_link(), for pad to pad links or the same as described
+ *    on media_create_intf_link(), for interface to entity links.
  */
 int media_entity_setup_link(struct media_link *link, u32 flags);
 
@@ -844,7 +852,7 @@ __must_check int media_entity_pipeline_start(struct media_entity *entity,
  * @entity: Starting entity
  * @pipe: Media pipeline to be assigned to all entities in the pipeline.
  *
- * Note: This is the non-locking version of media_entity_pipeline_start()
+ * ..note:: This is the non-locking version of media_entity_pipeline_start()
  */
 __must_check int __media_entity_pipeline_start(struct media_entity *entity,
 					       struct media_pipeline *pipe);
@@ -868,7 +876,7 @@ void media_entity_pipeline_stop(struct media_entity *entity);
  *
  * @entity: Starting entity
  *
- * Note: This is the non-locking version of media_entity_pipeline_stop()
+ * .. note:: This is the non-locking version of media_entity_pipeline_stop()
  */
 void __media_entity_pipeline_stop(struct media_entity *entity);
 
@@ -909,20 +917,21 @@ struct media_link *
  *
  *
  * Valid values for flags:
- * The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to
- *	the entity hardware. That's the default value for interfaces. An
- *	interface may be disabled if the hardware is busy due to the usage
- *	of some other interface that it is currently controlling the hardware.
- *	A typical example is an hybrid TV device that handle only one type of
- *	stream on a given time. So, when the digital TV is streaming,
- *	the V4L2 interfaces won't be enabled, as such device is not able to
- *	also stream analog TV or radio.
  *
- * Note:
+ * - The %MEDIA_LNK_FL_ENABLED flag indicates that the interface is connected to
+ *   the entity hardware. That's the default value for interfaces. An
+ *   interface may be disabled if the hardware is busy due to the usage
+ *   of some other interface that it is currently controlling the hardware.
+ *   A typical example is an hybrid TV device that handle only one type of
+ *   stream on a given time. So, when the digital TV is streaming,
+ *   the V4L2 interfaces won't be enabled, as such device is not able to
+ *   also stream analog TV or radio.
+ *
+ * .. note::
  *
- * Before calling this function, media_devnode_create() should be called for
- * the interface and media_device_register_entity() should be called for the
- * interface that will be part of the link.
+ *    Before calling this function, media_devnode_create() should be called for
+ *    the interface and media_device_register_entity() should be called for the
+ *    interface that will be part of the link.
  */
 __must_check media_create_intf_link(struct media_entity *entity,
 				    struct media_interface *intf,
@@ -932,7 +941,7 @@ __must_check media_create_intf_link(struct media_entity *entity,
  *
  * @link:	pointer to &media_link.
  *
- * Note: this is an unlocked version of media_remove_intf_link()
+ * .. note:: This is an unlocked version of media_remove_intf_link()
  */
 void __media_remove_intf_link(struct media_link *link);
 
@@ -941,7 +950,7 @@ void __media_remove_intf_link(struct media_link *link);
  *
  * @link:	pointer to &media_link.
  *
- * Note: prefer to use this one, instead of __media_remove_intf_link()
+ * .. note:: Prefer to use this one, instead of __media_remove_intf_link()
  */
 void media_remove_intf_link(struct media_link *link);
 
@@ -950,7 +959,7 @@ void media_remove_intf_link(struct media_link *link);
  *
  * @intf:	pointer to &media_interface
  *
- * Note: this is an unlocked version of media_remove_intf_links().
+ * .. note:: This is an unlocked version of media_remove_intf_links().
  */
 void __media_remove_intf_links(struct media_interface *intf);
 
@@ -959,12 +968,12 @@ void __media_remove_intf_links(struct media_interface *intf);
  *
  * @intf:	pointer to &media_interface
  *
- * Notes:
+ * .. note::
  *
- * this is called automatically when an entity is unregistered via
- * media_device_register_entity() and by media_devnode_remove().
+ *   #) This is called automatically when an entity is unregistered via
+ *      media_device_register_entity() and by media_devnode_remove().
  *
- * Prefer to use this one, instead of __media_remove_intf_links().
+ *   #) Prefer to use this one, instead of __media_remove_intf_links().
  */
 void media_remove_intf_links(struct media_interface *intf);
 
diff --git a/include/media/rc-core.h b/include/media/rc-core.h
index 324232cfc08d..10908e356b23 100644
--- a/include/media/rc-core.h
+++ b/include/media/rc-core.h
@@ -29,9 +29,16 @@ do {								\
 		printk(KERN_DEBUG pr_fmt(fmt), ##__VA_ARGS__);	\
 } while (0)
 
+/**
+ * enum rc_driver_type - type of the RC output
+ *
+ * @RC_DRIVER_SCANCODE:	Driver or hardware generates a scancode
+ * @RC_DRIVER_IR_RAW:	Driver or hardware generates pulse/space sequences.
+ *			It needs a Infra-Red pulse/space decoder
+ */
 enum rc_driver_type {
-	RC_DRIVER_SCANCODE = 0,	/* Driver or hardware generates a scancode */
-	RC_DRIVER_IR_RAW,	/* Needs a Infra-Red pulse/space decoder */
+	RC_DRIVER_SCANCODE = 0,
+	RC_DRIVER_IR_RAW,
 };
 
 /**
@@ -188,12 +195,46 @@ struct rc_dev {
  * Remote Controller, at sys/class/rc.
  */
 
+/**
+ * rc_allocate_device - Allocates a RC device
+ *
+ * returns a pointer to struct rc_dev.
+ */
 struct rc_dev *rc_allocate_device(void);
+
+/**
+ * rc_free_device - Frees a RC device
+ *
+ * @dev: pointer to struct rc_dev.
+ */
 void rc_free_device(struct rc_dev *dev);
+
+/**
+ * rc_register_device - Registers a RC device
+ *
+ * @dev: pointer to struct rc_dev.
+ */
 int rc_register_device(struct rc_dev *dev);
+
+/**
+ * rc_unregister_device - Unregisters a RC device
+ *
+ * @dev: pointer to struct rc_dev.
+ */
 void rc_unregister_device(struct rc_dev *dev);
 
+/**
+ * rc_open - Opens a RC device
+ *
+ * @rdev: pointer to struct rc_dev.
+ */
 int rc_open(struct rc_dev *rdev);
+
+/**
+ * rc_open - Closes a RC device
+ *
+ * @rdev: pointer to struct rc_dev.
+ */
 void rc_close(struct rc_dev *rdev);
 
 void rc_repeat(struct rc_dev *dev);
diff --git a/include/media/rc-map.h b/include/media/rc-map.h
index a459129dd554..daa75fcc1ff1 100644
--- a/include/media/rc-map.h
+++ b/include/media/rc-map.h
@@ -98,10 +98,25 @@ struct rc_map_list {
 
 /* Routines from rc-map.c */
 
+/**
+ * rc_map_register() - Registers a Remote Controler scancode map
+ *
+ * @map:	pointer to struct rc_map_list
+ */
 int rc_map_register(struct rc_map_list *map);
+
+/**
+ * rc_map_unregister() - Unregisters a Remote Controler scancode map
+ *
+ * @map:	pointer to struct rc_map_list
+ */
 void rc_map_unregister(struct rc_map_list *map);
+
+/**
+ * rc_map_get - gets an RC map from its name
+ * @name: name of the RC scancode map
+ */
 struct rc_map *rc_map_get(const char *name);
-void rc_map_init(void);
 
 /* Names of the several keytables defined in-kernel */
 
diff --git a/include/media/tuner-types.h b/include/media/tuner-types.h
index 094e112cc325..aed539068d2d 100644
--- a/include/media/tuner-types.h
+++ b/include/media/tuner-types.h
@@ -35,8 +35,12 @@ enum param_type {
  * those ranges, as they're defined inside the driver. This is used by
  * analog tuners that are compatible with the "Philips way" to setup the
  * tuners. On those devices, the tuner set is done via 4 bytes:
- *	divider byte1 (DB1), divider byte 2 (DB2), Control byte (CB) and
- *	band switch byte (BB).
+ *
+ *	#) divider byte1 (DB1)
+ *	#) divider byte 2 (DB2)
+ *	#) Control byte (CB)
+ *	#) band switch byte (BB)
+ *
  * Some tuners also have an additional optional Auxiliary byte (AB).
  */
 struct tuner_range {
diff --git a/include/media/tveeprom.h b/include/media/tveeprom.h
index 8be898739e0c..c56501ee0484 100644
--- a/include/media/tveeprom.h
+++ b/include/media/tveeprom.h
@@ -27,31 +27,43 @@ enum tveeprom_audio_processor {
  * struct tveeprom - Contains the fields parsed from Hauppauge eeproms
  *
  * @has_radio:			1 if the device has radio; 0 otherwise.
+ *
  * @has_ir:			If has_ir == 0, then it is unknown what the IR
  *				capabilities are. Otherwise:
- *					bit 0) 1 (= IR capabilities are known);
- *					bit 1) IR receiver present;
- *					bit 2) IR transmitter (blaster) present.
+ *				bit 0) 1 (= IR capabilities are known);
+ *				bit 1) IR receiver present;
+ *				bit 2) IR transmitter (blaster) present.
+ *
  * @has_MAC_address:		0: no MAC, 1: MAC present, 2: unknown.
  * @tuner_type:			type of the tuner (TUNER_*, as defined at
  *				include/media/tuner.h).
+ *
  * @tuner_formats:		Supported analog TV standards (V4L2_STD_*).
  * @tuner_hauppauge_model:	Hauppauge's code for the device model number.
  * @tuner2_type:		type of the second tuner (TUNER_*, as defined
  *				at include/media/tuner.h).
+ *
  * @tuner2_formats:		Tuner 2 supported analog TV standards
  *				(V4L2_STD_*).
+ *
  * @tuner2_hauppauge_model:	tuner 2 Hauppauge's code for the device model
  *				number.
+ *
  * @audio_processor:		analog audio decoder, as defined by enum
  *				tveeprom_audio_processor.
+ *
  * @decoder_processor:		Hauppauge's code for the decoder chipset.
  *				Unused by the drivers, as they probe the
  *				decoder based on the PCI or USB ID.
+ *
  * @model:			Hauppauge's model number
+ *
  * @revision:			Card revision number
+ *
  * @serial_number:		Card's serial number
+ *
  * @rev_str:			Card revision converted to number
+ *
  * @MAC_address:		MAC address for the network interface
  */
 struct tveeprom {
diff --git a/include/media/v4l2-async.h b/include/media/v4l2-async.h
index 1d6d7da4c45d..8e2a236a4d03 100644
--- a/include/media/v4l2-async.h
+++ b/include/media/v4l2-async.h
@@ -23,6 +23,19 @@ struct v4l2_async_notifier;
 /* A random max subdevice number, used to allocate an array on stack */
 #define V4L2_MAX_SUBDEVS 128U
 
+/**
+ * enum v4l2_async_match_type - type of asynchronous subdevice logic to be used
+ *	in order to identify a match
+ *
+ * @V4L2_ASYNC_MATCH_CUSTOM: Match will use the logic provided by &struct
+ * 	v4l2_async_subdev.match ops
+ * @V4L2_ASYNC_MATCH_DEVNAME: Match will use the device name
+ * @V4L2_ASYNC_MATCH_I2C: Match will check for I2C adapter ID and address
+ * @V4L2_ASYNC_MATCH_OF: Match will use OF node
+ *
+ * This enum is used by the asyncrhronous sub-device logic to define the
+ * algorithm that will be used to match an asynchronous device.
+ */
 enum v4l2_async_match_type {
 	V4L2_ASYNC_MATCH_CUSTOM,
 	V4L2_ASYNC_MATCH_DEVNAME,
@@ -91,9 +104,35 @@ struct v4l2_async_notifier {
 		       struct v4l2_async_subdev *asd);
 };
 
+/**
+ * v4l2_async_notifier_register - registers a subdevice asynchronous notifier
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @notifier: pointer to &struct v4l2_async_notifier
+ */
 int v4l2_async_notifier_register(struct v4l2_device *v4l2_dev,
 				 struct v4l2_async_notifier *notifier);
+
+/**
+ * v4l2_async_notifier_unregister - unregisters a subdevice asynchronous notifier
+ *
+ * @notifier: pointer to &struct v4l2_async_notifier
+ */
 void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier);
+
+/**
+ * v4l2_async_register_subdev - registers a sub-device to the asynchronous
+ * 	subdevice framework
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ */
 int v4l2_async_register_subdev(struct v4l2_subdev *sd);
+
+/**
+ * v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous
+ * 	subdevice framework
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ */
 void v4l2_async_unregister_subdev(struct v4l2_subdev *sd);
 #endif
diff --git a/include/media/v4l2-common.h b/include/media/v4l2-common.h
index 1cc0c5ba16b3..350cbf9fb10e 100644
--- a/include/media/v4l2-common.h
+++ b/include/media/v4l2-common.h
@@ -78,11 +78,26 @@
 			v4l2_printk(KERN_DEBUG, dev, fmt , ## arg); 	\
 	} while (0)
 
-/* ------------------------------------------------------------------------- */
-
-/* Control helper function */
+/**
+ * v4l2_ctrl_query_fill- Fill in a struct v4l2_queryctrl
+ *
+ * @qctrl: pointer to the &struct v4l2_queryctrl to be filled
+ * @min: minimum value for the control
+ * @max: maximum value for the control
+ * @step: control step
+ * @def: default value for the control
+ *
+ * Fills the &struct v4l2_queryctrl fields for the query control.
+ *
+ * .. note::
+ *
+ *    This function assumes that the @qctrl->id field is filled.
+ *
+ * Returns -EINVAL if the control is not known by the V4L2 core, 0 on success.
+ */
 
-int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl, s32 min, s32 max, s32 step, s32 def);
+int v4l2_ctrl_query_fill(struct v4l2_queryctrl *qctrl,
+			 s32 min, s32 max, s32 step, s32 def);
 
 /* ------------------------------------------------------------------------- */
 
@@ -96,23 +111,60 @@ struct v4l2_device;
 struct v4l2_subdev;
 struct v4l2_subdev_ops;
 
-
-/* Load an i2c module and return an initialized v4l2_subdev struct.
-   The client_type argument is the name of the chip that's on the adapter. */
+/**
+ * v4l2_i2c_new_subdev - Load an i2c module and return an initialized
+ *	&struct v4l2_subdev.
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @adapter: pointer to struct i2c_adapter
+ * @client_type:  name of the chip that's on the adapter.
+ * @addr: I2C address. If zero, it will use @probe_addrs
+ * @probe_addrs: array with a list of address. The last entry at such
+ * 	array should be %I2C_CLIENT_END.
+ *
+ * returns a &struct v4l2_subdev pointer.
+ */
 struct v4l2_subdev *v4l2_i2c_new_subdev(struct v4l2_device *v4l2_dev,
 		struct i2c_adapter *adapter, const char *client_type,
 		u8 addr, const unsigned short *probe_addrs);
 
 struct i2c_board_info;
 
+/**
+ * v4l2_i2c_new_subdev_board - Load an i2c module and return an initialized
+ *	&struct v4l2_subdev.
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @adapter: pointer to struct i2c_adapter
+ * @info: pointer to struct i2c_board_info used to replace the irq,
+ *	 platform_data and addr arguments.
+ * @probe_addrs: array with a list of address. The last entry at such
+ * 	array should be %I2C_CLIENT_END.
+ *
+ * returns a &struct v4l2_subdev pointer.
+ */
 struct v4l2_subdev *v4l2_i2c_new_subdev_board(struct v4l2_device *v4l2_dev,
 		struct i2c_adapter *adapter, struct i2c_board_info *info,
 		const unsigned short *probe_addrs);
 
-/* Initialize a v4l2_subdev with data from an i2c_client struct */
+/**
+ * v4l2_i2c_subdev_init - Initializes a &struct v4l2_subdev with data from
+ *	an i2c_client struct.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @client: pointer to struct i2c_client
+ * @ops: pointer to &struct v4l2_subdev_ops
+ */
 void v4l2_i2c_subdev_init(struct v4l2_subdev *sd, struct i2c_client *client,
 		const struct v4l2_subdev_ops *ops);
-/* Return i2c client address of v4l2_subdev. */
+
+/**
+ * v4l2_i2c_subdev_addr - returns i2c client address of &struct v4l2_subdev.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ *
+ * Returns the address of an I2C sub-device
+ */
 unsigned short v4l2_i2c_subdev_addr(struct v4l2_subdev *sd);
 
 enum v4l2_i2c_tuner_type {
@@ -137,12 +189,28 @@ const unsigned short *v4l2_i2c_tuner_addrs(enum v4l2_i2c_tuner_type type);
 
 struct spi_device;
 
-/* Load an spi module and return an initialized v4l2_subdev struct.
-   The client_type argument is the name of the chip that's on the adapter. */
+/**
+ *  v4l2_spi_new_subdev - Load an spi module and return an initialized
+ *	&struct v4l2_subdev.
+ *
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device.
+ * @master: pointer to struct spi_master.
+ * @info: pointer to struct spi_board_info.
+ *
+ * returns a &struct v4l2_subdev pointer.
+ */
 struct v4l2_subdev *v4l2_spi_new_subdev(struct v4l2_device *v4l2_dev,
 		struct spi_master *master, struct spi_board_info *info);
 
-/* Initialize a v4l2_subdev with data from an spi_device struct */
+/**
+ * v4l2_spi_subdev_init - Initialize a v4l2_subdev with data from an
+ *	spi_device struct.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @spi: pointer to struct spi_device.
+ * @ops: pointer to &struct v4l2_subdev_ops
+ */
 void v4l2_spi_subdev_init(struct v4l2_subdev *sd, struct spi_device *spi,
 		const struct v4l2_subdev_ops *ops);
 #endif
diff --git a/include/media/v4l2-ctrls.h b/include/media/v4l2-ctrls.h
index 8b59336b2217..178a88d45aea 100644
--- a/include/media/v4l2-ctrls.h
+++ b/include/media/v4l2-ctrls.h
@@ -1,21 +1,17 @@
 /*
-    V4L2 controls support header.
-
-    Copyright (C) 2010  Hans Verkuil <hverkuil@xs4all.nl>
-
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software
-    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ *  V4L2 controls support header.
+ *
+ *  Copyright (C) 2010  Hans Verkuil <hverkuil@xs4all.nl>
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
  */
 
 #ifndef _V4L2_CTRLS_H
@@ -58,6 +54,7 @@ union v4l2_ctrl_ptr {
 
 /**
  * struct v4l2_ctrl_ops - The control operations that the driver has to provide.
+ *
  * @g_volatile_ctrl: Get a new value for this control. Generally only relevant
  *		for volatile (and usually read-only) controls such as a control
  *		that returns the current signal strength which changes
@@ -77,12 +74,13 @@ struct v4l2_ctrl_ops {
 
 /**
  * struct v4l2_ctrl_type_ops - The control type operations that the driver
- * 			       has to provide.
+ *			       has to provide.
  *
  * @equal: return true if both values are equal.
  * @init: initialize the value.
  * @log: log the value.
- * @validate: validate the value. Return 0 on success and a negative value otherwise.
+ * @validate: validate the value. Return 0 on success and a negative value
+ *	otherwise.
  */
 struct v4l2_ctrl_type_ops {
 	bool (*equal)(const struct v4l2_ctrl *ctrl, u32 idx,
@@ -99,6 +97,7 @@ typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
 
 /**
  * struct v4l2_ctrl - The control structure.
+ *
  * @node:	The list node.
  * @ev_subs:	The list of control event subscriptions.
  * @handler:	The handler that owns the control.
@@ -106,7 +105,7 @@ typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
  * @ncontrols:	Number of controls in cluster array.
  * @done:	Internal flag: set for each processed control.
  * @is_new:	Set when the user specified a new value for this control. It
- *		is also set when called from v4l2_ctrl_handler_setup. Drivers
+ *		is also set when called from v4l2_ctrl_handler_setup(). Drivers
  *		should never set this flag.
  * @has_changed: Set when the current value differs from the new value. Drivers
  *		should never use this flag.
@@ -119,9 +118,10 @@ typedef void (*v4l2_ctrl_notify_fnc)(struct v4l2_ctrl *ctrl, void *priv);
  *		set this flag directly.
  * @is_int:    If set, then this control has a simple integer value (i.e. it
  *		uses ctrl->val).
- * @is_string: If set, then this control has type V4L2_CTRL_TYPE_STRING.
- * @is_ptr:	If set, then this control is an array and/or has type >= V4L2_CTRL_COMPOUND_TYPES
- *		and/or has type V4L2_CTRL_TYPE_STRING. In other words, struct
+ * @is_string: If set, then this control has type %V4L2_CTRL_TYPE_STRING.
+ * @is_ptr:	If set, then this control is an array and/or has type >=
+ *		%V4L2_CTRL_COMPOUND_TYPES
+ *		and/or has type %V4L2_CTRL_TYPE_STRING. In other words, &struct
  *		v4l2_ext_control uses field p to point to the data.
  * @is_array: If set, then this control contains an N-dimensional array.
  * @has_volatiles: If set, then one or more members of the cluster are volatile.
@@ -177,7 +177,8 @@ struct v4l2_ctrl {
 	struct list_head ev_subs;
 	struct v4l2_ctrl_handler *handler;
 	struct v4l2_ctrl **cluster;
-	unsigned ncontrols;
+	unsigned int ncontrols;
+
 	unsigned int done:1;
 
 	unsigned int is_new:1;
@@ -223,10 +224,12 @@ struct v4l2_ctrl {
 
 /**
  * struct v4l2_ctrl_ref - The control reference.
+ *
  * @node:	List node for the sorted list.
  * @next:	Single-link list node for the hash.
  * @ctrl:	The actual control information.
- * @helper:	Pointer to helper struct. Used internally in prepare_ext_ctrls().
+ * @helper:	Pointer to helper struct. Used internally in
+ *		prepare_ext_ctrls().
  *
  * Each control handler has a list of these refs. The list_head is used to
  * keep a sorted-by-control-ID list of all controls, while the next pointer
@@ -241,8 +244,9 @@ struct v4l2_ctrl_ref {
 
 /**
  * struct v4l2_ctrl_handler - The control handler keeps track of all the
- * controls: both the controls owned by the handler and those inherited
- * from other handlers.
+ *	controls: both the controls owned by the handler and those inherited
+ *	from other handlers.
+ *
  * @_lock:	Default for "lock".
  * @lock:	Lock to control access to this handler and its controls.
  *		May be replaced by the user right after init.
@@ -252,7 +256,8 @@ struct v4l2_ctrl_ref {
  *		control is needed multiple times, so this is a simple
  *		optimization.
  * @buckets:	Buckets for the hashing. Allows for quick control lookup.
- * @notify:	A notify callback that is called whenever the control changes value.
+ * @notify:	A notify callback that is called whenever the control changes
+ *		value.
  *		Note that the handler's lock is held when the notify function
  *		is called!
  * @notify_priv: Passed as argument to the v4l2_ctrl notify callback.
@@ -274,6 +279,7 @@ struct v4l2_ctrl_handler {
 
 /**
  * struct v4l2_ctrl_config - Control configuration structure.
+ *
  * @ops:	The control ops.
  * @type_ops:	The control type ops. Only needed for compound controls.
  * @id:	The control ID.
@@ -282,7 +288,7 @@ struct v4l2_ctrl_handler {
  * @min:	The control's minimum value.
  * @max:	The control's maximum value.
  * @step:	The control's step value for non-menu controls.
- * @def: 	The control's default value.
+ * @def:	The control's default value.
  * @dims:	The size of each dimension.
  * @elem_size:	The size in bytes of the control.
  * @flags:	The control's flags.
@@ -297,7 +303,7 @@ struct v4l2_ctrl_handler {
  *		is in addition to the menu_skip_mask above). The last entry
  *		must be NULL.
  * @qmenu_int:	A const s64 integer array for all menu items of the type
- * 		V4L2_CTRL_TYPE_INTEGER_MENU.
+ *		V4L2_CTRL_TYPE_INTEGER_MENU.
  * @is_private: If set, then this control is private to its handler and it
  *		will not be added to any other handlers.
  */
@@ -320,20 +326,31 @@ struct v4l2_ctrl_config {
 	unsigned int is_private:1;
 };
 
-/*
- * v4l2_ctrl_fill() - Fill in the control fields based on the control ID.
+/**
+ * v4l2_ctrl_fill - Fill in the control fields based on the control ID.
+ *
+ * @id: ID of the control
+ * @name: name of the control
+ * @type: type of the control
+ * @min: minimum value for the control
+ * @max: maximum value for the control
+ * @step: control step
+ * @def: default value for the control
+ * @flags: flags to be used on the control
  *
  * This works for all standard V4L2 controls.
  * For non-standard controls it will only fill in the given arguments
- * and @name will be NULL.
+ * and @name will be %NULL.
  *
  * This function will overwrite the contents of @name, @type and @flags.
  * The contents of @min, @max, @step and @def may be modified depending on
  * the type.
  *
- * Do not use in drivers! It is used internally for backwards compatibility
- * control handling only. Once all drivers are converted to use the new
- * control framework this function will no longer be exported.
+ * .. note::
+ *
+ *    Do not use in drivers! It is used internally for backwards compatibility
+ *    control handling only. Once all drivers are converted to use the new
+ *    control framework this function will no longer be exported.
  */
 void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
 		    s64 *min, s64 *max, u64 *step, s64 *def, u32 *flags);
@@ -359,7 +376,7 @@ void v4l2_ctrl_fill(u32 id, const char **name, enum v4l2_ctrl_type *type,
  * macro that hides the @key and @name arguments.
  */
 int v4l2_ctrl_handler_init_class(struct v4l2_ctrl_handler *hdl,
-				 unsigned nr_of_controls_hint,
+				 unsigned int nr_of_controls_hint,
 				 struct lock_class_key *key, const char *name);
 
 #ifdef CONFIG_LOCKDEP
@@ -436,7 +453,8 @@ void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
 
 /**
  * v4l2_ctrl_new_custom() - Allocate and initialize a new custom V4L2
- * control.
+ *	control.
+ *
  * @hdl:	The control handler.
  * @cfg:	The control's configuration data.
  * @priv:	The control's driver-specific private data.
@@ -445,17 +463,20 @@ void v4l2_ctrl_handler_log_status(struct v4l2_ctrl_handler *hdl,
  * and @hdl->error is set to the error code (if it wasn't set already).
  */
 struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
-			const struct v4l2_ctrl_config *cfg, void *priv);
+				       const struct v4l2_ctrl_config *cfg,
+				       void *priv);
 
 /**
- * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu control.
+ * v4l2_ctrl_new_std() - Allocate and initialize a new standard V4L2 non-menu
+ *	control.
+ *
  * @hdl:	The control handler.
  * @ops:	The control ops.
- * @id:	The control ID.
+ * @id:		The control ID.
  * @min:	The control's minimum value.
  * @max:	The control's maximum value.
  * @step:	The control's step value
- * @def: 	The control's default value.
+ * @def:	The control's default value.
  *
  * If the &v4l2_ctrl struct could not be allocated, or the control
  * ID is not known, then NULL is returned and @hdl->error is set to the
@@ -466,22 +487,25 @@ struct v4l2_ctrl *v4l2_ctrl_new_custom(struct v4l2_ctrl_handler *hdl,
  * Use v4l2_ctrl_new_std_menu() when adding menu controls.
  */
 struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
-			const struct v4l2_ctrl_ops *ops,
-			u32 id, s64 min, s64 max, u64 step, s64 def);
+				    const struct v4l2_ctrl_ops *ops,
+				    u32 id, s64 min, s64 max, u64 step,
+				    s64 def);
 
 /**
- * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2 menu control.
+ * v4l2_ctrl_new_std_menu() - Allocate and initialize a new standard V4L2
+ *	menu control.
+ *
  * @hdl:	The control handler.
  * @ops:	The control ops.
- * @id:	The control ID.
+ * @id:		The control ID.
  * @max:	The control's maximum value.
- * @mask: 	The control's skip mask for menu controls. This makes it
+ * @mask:	The control's skip mask for menu controls. This makes it
  *		easy to skip menu items that are not valid. If bit X is set,
  *		then menu item X is skipped. Of course, this only works for
  *		menus with <= 64 menu items. There are no menus that come
  *		close to that number, so this is OK. Should we ever need more,
  *		then this will have to be extended to a bit array.
- * @def: 	The control's default value.
+ * @def:	The control's default value.
  *
  * Same as v4l2_ctrl_new_std(), but @min is set to 0 and the @mask value
  * determines which menu items are to be skipped.
@@ -489,12 +513,13 @@ struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
  * If @id refers to a non-menu control, then this function will return NULL.
  */
 struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
-			const struct v4l2_ctrl_ops *ops,
-			u32 id, u8 max, u64 mask, u8 def);
+					 const struct v4l2_ctrl_ops *ops,
+					 u32 id, u8 max, u64 mask, u8 def);
 
 /**
  * v4l2_ctrl_new_std_menu_items() - Create a new standard V4L2 menu control
- * with driver specific menu.
+ *	with driver specific menu.
+ *
  * @hdl:	The control handler.
  * @ops:	The control ops.
  * @id:	The control ID.
@@ -513,11 +538,14 @@ struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
  *
  */
 struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl,
-			const struct v4l2_ctrl_ops *ops, u32 id, u8 max,
-			u64 mask, u8 def, const char * const *qmenu);
+					       const struct v4l2_ctrl_ops *ops,
+					       u32 id, u8 max,
+					       u64 mask, u8 def,
+					       const char * const *qmenu);
 
 /**
  * v4l2_ctrl_new_int_menu() - Create a new standard V4L2 integer menu control.
+ *
  * @hdl:	The control handler.
  * @ops:	The control ops.
  * @id:	The control ID.
@@ -528,15 +556,20 @@ struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(struct v4l2_ctrl_handler *hdl,
  * Same as v4l2_ctrl_new_std_menu(), but @mask is set to 0 and it additionaly
  * takes as an argument an array of integers determining the menu items.
  *
- * If @id refers to a non-integer-menu control, then this function will return NULL.
+ * If @id refers to a non-integer-menu control, then this function will
+ * return %NULL.
  */
 struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
-			const struct v4l2_ctrl_ops *ops,
-			u32 id, u8 max, u8 def, const s64 *qmenu_int);
+					 const struct v4l2_ctrl_ops *ops,
+					 u32 id, u8 max, u8 def,
+					 const s64 *qmenu_int);
+
+typedef bool (*v4l2_ctrl_filter)(const struct v4l2_ctrl *ctrl);
 
 /**
  * v4l2_ctrl_add_handler() - Add all controls from handler @add to
- * handler @hdl.
+ *	handler @hdl.
+ *
  * @hdl:	The control handler.
  * @add:	The control handler whose controls you want to add to
  *		the @hdl control handler.
@@ -550,10 +583,11 @@ struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
  */
 int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
 			  struct v4l2_ctrl_handler *add,
-			  bool (*filter)(const struct v4l2_ctrl *ctrl));
+			  v4l2_ctrl_filter filter);
 
 /**
  * v4l2_ctrl_radio_filter() - Standard filter for radio controls.
+ *
  * @ctrl:	The control that is filtered.
  *
  * This will return true for any controls that are valid for radio device
@@ -565,16 +599,19 @@ int v4l2_ctrl_add_handler(struct v4l2_ctrl_handler *hdl,
 bool v4l2_ctrl_radio_filter(const struct v4l2_ctrl *ctrl);
 
 /**
- * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging to that cluster.
+ * v4l2_ctrl_cluster() - Mark all controls in the cluster as belonging
+ *	to that cluster.
+ *
  * @ncontrols:	The number of controls in this cluster.
- * @controls: 	The cluster control array of size @ncontrols.
+ * @controls:	The cluster control array of size @ncontrols.
  */
-void v4l2_ctrl_cluster(unsigned ncontrols, struct v4l2_ctrl **controls);
+void v4l2_ctrl_cluster(unsigned int ncontrols, struct v4l2_ctrl **controls);
 
 
 /**
- * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging to
- * that cluster and set it up for autofoo/foo-type handling.
+ * v4l2_ctrl_auto_cluster() - Mark all controls in the cluster as belonging
+ *	to that cluster and set it up for autofoo/foo-type handling.
+ *
  * @ncontrols:	The number of controls in this cluster.
  * @controls:	The cluster control array of size @ncontrols. The first control
  *		must be the 'auto' control (e.g. autogain, autoexposure, etc.)
@@ -602,12 +639,14 @@ void v4l2_ctrl_cluster(unsigned ncontrols, struct v4l2_ctrl **controls);
  * on the autofoo control and V4L2_CTRL_FLAG_INACTIVE on the foo control(s)
  * if autofoo is in auto mode.
  */
-void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
-			u8 manual_val, bool set_volatile);
+void v4l2_ctrl_auto_cluster(unsigned int ncontrols,
+			    struct v4l2_ctrl **controls,
+			    u8 manual_val, bool set_volatile);
 
 
 /**
  * v4l2_ctrl_find() - Find a control with the given ID.
+ *
  * @hdl:	The control handler.
  * @id:	The control ID to find.
  *
@@ -632,6 +671,7 @@ void v4l2_ctrl_activate(struct v4l2_ctrl *ctrl, bool active);
 
 /**
  * v4l2_ctrl_grab() - Mark the control as grabbed or not grabbed.
+ *
  * @ctrl:	The control to (de)activate.
  * @grabbed:	True if the control should become grabbed.
  *
@@ -671,6 +711,7 @@ int __v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
 
 /**
  * v4l2_ctrl_modify_range() - Update the range of a control.
+ *
  * @ctrl:	The control to update.
  * @min:	The control's minimum value.
  * @max:	The control's maximum value.
@@ -701,6 +742,7 @@ static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
 
 /**
  * v4l2_ctrl_notify() - Function to set a notify callback for a control.
+ *
  * @ctrl:	The control.
  * @notify:	The callback function.
  * @priv:	The callback private handle, passed as argument to the callback.
@@ -712,10 +754,12 @@ static inline int v4l2_ctrl_modify_range(struct v4l2_ctrl *ctrl,
  * There can be only one notify. If another already exists, then a WARN_ON
  * will be issued and the function will do nothing.
  */
-void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify, void *priv);
+void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl, v4l2_ctrl_notify_fnc notify,
+		      void *priv);
 
 /**
  * v4l2_ctrl_get_name() - Get the name of the control
+ *
  * @id:		The control ID.
  *
  * This function returns the name of the given control ID or NULL if it isn't
@@ -725,6 +769,7 @@ const char *v4l2_ctrl_get_name(u32 id);
 
 /**
  * v4l2_ctrl_get_menu() - Get the menu string array of the control
+ *
  * @id:		The control ID.
  *
  * This function returns the NULL-terminated menu string array name of the
@@ -734,6 +779,7 @@ const char * const *v4l2_ctrl_get_menu(u32 id);
 
 /**
  * v4l2_ctrl_get_int_menu() - Get the integer menu array of the control
+ *
  * @id:		The control ID.
  * @len:	The size of the integer array.
  *
@@ -743,7 +789,9 @@ const char * const *v4l2_ctrl_get_menu(u32 id);
 const s64 *v4l2_ctrl_get_int_menu(u32 id, u32 *len);
 
 /**
- * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from within a driver.
+ * v4l2_ctrl_g_ctrl() - Helper function to get the control's value from
+ *	within a driver.
+ *
  * @ctrl:	The control.
  *
  * This returns the control's value safely by going through the control
@@ -756,8 +804,9 @@ s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
 
 /**
  * __v4l2_ctrl_s_ctrl() - Unlocked variant of v4l2_ctrl_s_ctrl().
+ *
  * @ctrl:	The control.
- * @val:	The new value.
+ * @val:	TheControls name new value.
  *
  * This sets the control's new value safely by going through the control
  * framework. This function assumes the control's handler is already locked,
@@ -767,7 +816,9 @@ s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
  */
 int __v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
 
-/** v4l2_ctrl_s_ctrl() - Helper function to set the control's value from within a driver.
+/**
+ * v4l2_ctrl_s_ctrl() - Helper function to set the control's value from
+ *	within a driver.
  * @ctrl:	The control.
  * @val:	The new value.
  *
@@ -791,6 +842,7 @@ static inline int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val)
 /**
  * v4l2_ctrl_g_ctrl_int64() - Helper function to get a 64-bit control's value
  *	from within a driver.
+ *
  * @ctrl:	The control.
  *
  * This returns the control's value safely by going through the control
@@ -815,7 +867,8 @@ s64 v4l2_ctrl_g_ctrl_int64(struct v4l2_ctrl *ctrl);
  */
 int __v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val);
 
-/** v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
+/**
+ * v4l2_ctrl_s_ctrl_int64() - Helper function to set a 64-bit control's value
  *	from within a driver.
  *
  * @ctrl:	The control.
@@ -838,7 +891,8 @@ static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)
 	return rval;
 }
 
-/** __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
+/**
+ * __v4l2_ctrl_s_ctrl_string() - Unlocked variant of v4l2_ctrl_s_ctrl_string().
  *
  * @ctrl:	The control.
  * @s:		The new string.
@@ -851,12 +905,13 @@ static inline int v4l2_ctrl_s_ctrl_int64(struct v4l2_ctrl *ctrl, s64 val)
  */
 int __v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s);
 
-/** v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
+/**
+ * v4l2_ctrl_s_ctrl_string() - Helper function to set a control's string value
  *	 from within a driver.
  *
  * @ctrl:	The control.
  * @s:		The new string.
- *
+ *Controls name
  * This sets the control's new string safely by going through the control
  * framework. This function will lock the control's handler, so it cannot be
  * used from within the &v4l2_ctrl_ops functions.
@@ -876,39 +931,179 @@ static inline int v4l2_ctrl_s_ctrl_string(struct v4l2_ctrl *ctrl, const char *s)
 
 /* Internal helper functions that deal with control events. */
 extern const struct v4l2_subscribed_event_ops v4l2_ctrl_sub_ev_ops;
+
+/**
+ * v4l2_ctrl_replace - Function to be used as a callback to
+ *	&struct v4l2_subscribed_event_ops replace\(\)
+ *
+ * @old: pointer to :ref:`struct v4l2_event <v4l2-event>` with the reported
+ *	 event;
+ * @new: pointer to :ref:`struct v4l2_event <v4l2-event>` with the modified
+ *	 event;
+ */
 void v4l2_ctrl_replace(struct v4l2_event *old, const struct v4l2_event *new);
+
+/**
+ * v4l2_ctrl_merge - Function to be used as a callback to
+ *	&struct v4l2_subscribed_event_ops merge(\)
+ *
+ * @old: pointer to :ref:`struct v4l2_event <v4l2-event>` with the reported
+ *	 event;
+ * @new: pointer to :ref:`struct v4l2_event <v4l2-event>` with the merged
+ *	 event;
+ */
 void v4l2_ctrl_merge(const struct v4l2_event *old, struct v4l2_event *new);
 
-/* Can be used as a vidioc_log_status function that just dumps all controls
-   associated with the filehandle. */
+/**
+ * v4l2_ctrl_log_status - helper function to implement %VIDIOC_LOG_STATUS ioctl
+ *
+ * @file: pointer to struct file
+ * @fh: unused. Kept just to be compatible to the arguments expected by
+ *	&struct v4l2_ioctl_ops.vidioc_log_status.
+ *
+ * Can be used as a vidioc_log_status function that just dumps all controls
+ * associated with the filehandle.
+ */
 int v4l2_ctrl_log_status(struct file *file, void *fh);
 
-/* Can be used as a vidioc_subscribe_event function that just subscribes
-   control events. */
+/**
+ * v4l2_ctrl_subscribe_event - Subscribes to an event
+ *
+ *
+ * @fh: pointer to struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ *
+ * Can be used as a vidioc_subscribe_event function that just subscribes
+ * control events.
+ */
 int v4l2_ctrl_subscribe_event(struct v4l2_fh *fh,
 				const struct v4l2_event_subscription *sub);
 
-/* Can be used as a poll function that just polls for control events. */
+/**
+ * v4l2_ctrl_poll - function to be used as a callback to the poll()
+ *	That just polls for control events.
+ *
+ * @file: pointer to struct file
+ * @wait: pointer to struct poll_table_struct
+ */
 unsigned int v4l2_ctrl_poll(struct file *file, struct poll_table_struct *wait);
 
-/* Helpers for ioctl_ops. If hdl == NULL then they will all return -EINVAL. */
+/* Helpers for ioctl_ops */
+
+/**
+ * v4l2_queryctrl - Helper function to implement
+ *	:ref:`VIDIOC_QUERYCTRL <vidioc_queryctrl>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @qc: pointer to &struct v4l2_queryctrl
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
 int v4l2_queryctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_queryctrl *qc);
-int v4l2_query_ext_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_query_ext_ctrl *qc);
+
+/**
+ * v4l2_query_ext_ctrl - Helper function to implement
+ *	 :ref:`VIDIOC_QUERY_EXT_CTRL <vidioc_queryctrl>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @qc: pointer to &struct v4l2_query_ext_ctrl
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
+int v4l2_query_ext_ctrl(struct v4l2_ctrl_handler *hdl,
+			struct v4l2_query_ext_ctrl *qc);
+
+/**
+ * v4l2_querymenu - Helper function to implement
+ *	:ref:`VIDIOC_QUERYMENU <vidioc_queryctrl>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @qm: pointer to &struct v4l2_querymenu
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
 int v4l2_querymenu(struct v4l2_ctrl_handler *hdl, struct v4l2_querymenu *qm);
+
+/**
+ * v4l2_g_ctrl - Helper function to implement
+ *	:ref:`VIDIOC_G_CTRL <vidioc_g_ctrl>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @ctrl: pointer to &struct v4l2_control
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
 int v4l2_g_ctrl(struct v4l2_ctrl_handler *hdl, struct v4l2_control *ctrl);
+
+/**
+ * v4l2_s_ctrl - Helper function to implement
+ *	:ref:`VIDIOC_S_CTRL <vidioc_g_ctrl>` ioctl
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ *
+ * @ctrl: pointer to &struct v4l2_control
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
 int v4l2_s_ctrl(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
-						struct v4l2_control *ctrl);
-int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *c);
-int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl, struct v4l2_ext_controls *c);
+		struct v4l2_control *ctrl);
+
+/**
+ * v4l2_g_ext_ctrls - Helper function to implement
+ *	:ref:`VIDIOC_G_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @c: pointer to &struct v4l2_ext_controls
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
+int v4l2_g_ext_ctrls(struct v4l2_ctrl_handler *hdl,
+		     struct v4l2_ext_controls *c);
+
+/**
+ * v4l2_try_ext_ctrls - Helper function to implement
+ *	:ref:`VIDIOC_TRY_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ *
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @c: pointer to &struct v4l2_ext_controls
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
+int v4l2_try_ext_ctrls(struct v4l2_ctrl_handler *hdl,
+		       struct v4l2_ext_controls *c);
+
+/**
+ * v4l2_s_ext_ctrls - Helper function to implement
+ *	:ref:`VIDIOC_S_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @hdl: pointer to &struct v4l2_ctrl_handler
+ * @c: pointer to &struct v4l2_ext_controls
+ *
+ * If hdl == NULL then they will all return -EINVAL.
+ */
 int v4l2_s_ext_ctrls(struct v4l2_fh *fh, struct v4l2_ctrl_handler *hdl,
-						struct v4l2_ext_controls *c);
+		     struct v4l2_ext_controls *c);
 
-/* Can be used as a subscribe_event function that just subscribes control
-   events. */
+/**
+ * v4l2_ctrl_subdev_subscribe_event - Helper function to implement
+ * 	as a &struct v4l2_subdev_core_ops subscribe_event function
+ *	that just subscribes control events.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ */
 int v4l2_ctrl_subdev_subscribe_event(struct v4l2_subdev *sd, struct v4l2_fh *fh,
 				     struct v4l2_event_subscription *sub);
 
-/* Log all controls owned by subdev's control handler. */
+/**
+ * v4l2_ctrl_subdev_log_status - Log all controls owned by subdev's control
+ *	 handler.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ */
 int v4l2_ctrl_subdev_log_status(struct v4l2_subdev *sd);
 
 #endif
diff --git a/include/media/v4l2-dev.h b/include/media/v4l2-dev.h
index 25a3190308fb..a122b1bd40f9 100644
--- a/include/media/v4l2-dev.h
+++ b/include/media/v4l2-dev.h
@@ -47,19 +47,105 @@ struct v4l2_ctrl_handler;
 
 /* Priority helper functions */
 
+/**
+ * struct v4l2_prio_state - stores the priority states
+ *
+ * @prios: array with elements to store the array priorities
+ *
+ *
+ * .. note::
+ *    The size of @prios array matches the number of priority types defined
+ *    by :ref:`enum v4l2_priority <v4l2-priority>`.
+ */
 struct v4l2_prio_state {
 	atomic_t prios[4];
 };
 
+/**
+ * v4l2_prio_init - initializes a struct v4l2_prio_state
+ *
+ * @global: pointer to &struct v4l2_prio_state
+ */
 void v4l2_prio_init(struct v4l2_prio_state *global);
+
+/**
+ * v4l2_prio_change - changes the v4l2 file handler priority
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: pointer to the desired priority, as defined by :ref:`enum v4l2_priority <v4l2-priority>`
+ * @new: Priority type requested, as defined by :ref:`enum v4l2_priority <v4l2-priority>`.
+ *
+ * .. note::
+ *	This function should be used only by the V4L2 core.
+ */
 int v4l2_prio_change(struct v4l2_prio_state *global, enum v4l2_priority *local,
 		     enum v4l2_priority new);
+
+/**
+ * v4l2_prio_open - Implements the priority logic for a file handler open
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: pointer to the desired priority, as defined by :ref:`enum v4l2_priority <v4l2-priority>`
+ *
+ * .. note::
+ *	This function should be used only by the V4L2 core.
+ */
 void v4l2_prio_open(struct v4l2_prio_state *global, enum v4l2_priority *local);
+
+/**
+ * v4l2_prio_close - Implements the priority logic for a file handler close
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: priority to be released, as defined by :ref:`enum v4l2_priority <v4l2-priority>`
+ *
+ * .. note::
+ *	This function should be used only by the V4L2 core.
+ */
 void v4l2_prio_close(struct v4l2_prio_state *global, enum v4l2_priority local);
+
+/**
+ * v4l2_prio_max - Return the maximum priority, as stored at the @global array.
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ *
+ * .. note::
+ *	This function should be used only by the V4L2 core.
+ */
 enum v4l2_priority v4l2_prio_max(struct v4l2_prio_state *global);
-int v4l2_prio_check(struct v4l2_prio_state *global, enum v4l2_priority local);
 
+/**
+ * v4l2_prio_close - Implements the priority logic for a file handler close
+ *
+ * @global: pointer to the &struct v4l2_prio_state of the device node.
+ * @local: desired priority, as defined by :ref:`enum v4l2_priority <v4l2-priority>` local
+ *
+ * .. note::
+ *	This function should be used only by the V4L2 core.
+ */
+int v4l2_prio_check(struct v4l2_prio_state *global, enum v4l2_priority local);
 
+/**
+ * struct v4l2_file_operations - fs operations used by a V4L2 device
+ *
+ * @owner: pointer to struct module
+ * @read: operations needed to implement the read() syscall
+ * @write: operations needed to implement the write() syscall
+ * @poll: operations needed to implement the poll() syscall
+ * @unlocked_ioctl: operations needed to implement the ioctl() syscall
+ * @compat_ioctl32: operations needed to implement the ioctl() syscall for
+ *	the special case where the Kernel uses 64 bits instructions, but
+ *	the userspace uses 32 bits.
+ * @get_unmapped_area: called by the mmap() syscall, used when %!CONFIG_MMU
+ * @mmap: operations needed to implement the mmap() syscall
+ * @open: operations needed to implement the open() syscall
+ * @release: operations needed to implement the release() syscall
+ *
+ * .. note::
+ *
+ *	Those operations are used to implemente the fs struct file_operations
+ *	at the V4L2 drivers. The V4L2 core overrides the fs ops with some
+ *	extra logic needed by the subsystem.
+ */
 struct v4l2_file_operations {
 	struct module *owner;
 	ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
@@ -82,6 +168,47 @@ struct v4l2_file_operations {
  *	the common handler
  */
 
+/**
+ * struct video_device - Structure used to create and manage the V4L2 device
+ *	nodes.
+ *
+ * @entity: &struct media_entity
+ * @intf_devnode: pointer to &struct media_intf_devnode
+ * @pipe: &struct media_pipeline
+ * @fops: pointer to &struct v4l2_file_operations for the video device
+ * @device_caps: device capabilities as used in v4l2_capabilities
+ * @dev: &struct device for the video device
+ * @cdev: character device
+ * @v4l2_dev: pointer to &struct v4l2_device parent
+ * @dev_parent: pointer to &struct device parent
+ * @ctrl_handler: Control handler associated with this device node.
+ *	 May be NULL.
+ * @queue: &struct vb2_queue associated with this device node. May be NULL.
+ * @prio: pointer to &struct v4l2_prio_state with device's Priority state.
+ *	 If NULL, then v4l2_dev->prio will be used.
+ * @name: video device name
+ * @vfl_type: V4L device type
+ * @vfl_dir: V4L receiver, transmitter or m2m
+ * @minor: device node 'minor'. It is set to -1 if the registration failed
+ * @num: number of the video device node
+ * @flags: video device flags. Use bitops to set/clear/test flags
+ * @index: attribute to differentiate multiple indices on one physical device
+ * @fh_lock: Lock for all v4l2_fhs
+ * @fh_list: List of &struct v4l2_fh
+ * @dev_debug: Internal device debug flags, not for use by drivers
+ * @tvnorms: Supported tv norms
+ *
+ * @release: video device release() callback
+ * @ioctl_ops: pointer to &struct v4l2_ioctl_ops with ioctl callbacks
+ *
+ * @valid_ioctls: bitmap with the valid ioctls for this device
+ * @disable_locking: bitmap with the ioctls that don't require locking
+ * @lock: pointer to &struct mutex serialization lock
+ *
+ * .. note::
+ *	Only set @dev_parent if that can't be deduced from @v4l2_dev.
+ */
+
 struct video_device
 {
 #if defined(CONFIG_MEDIA_CONTROLLER)
@@ -89,59 +216,45 @@ struct video_device
 	struct media_intf_devnode *intf_devnode;
 	struct media_pipeline pipe;
 #endif
-	/* device ops */
 	const struct v4l2_file_operations *fops;
 
-	/* device capabilities as used in v4l2_capabilities */
 	u32 device_caps;
 
 	/* sysfs */
-	struct device dev;		/* v4l device */
-	struct cdev *cdev;		/* character device */
+	struct device dev;
+	struct cdev *cdev;
 
-	struct v4l2_device *v4l2_dev;	/* v4l2_device parent */
-	/* Only set parent if that can't be deduced from v4l2_dev */
-	struct device *dev_parent;	/* device parent */
+	struct v4l2_device *v4l2_dev;
+	struct device *dev_parent;
 
-	/* Control handler associated with this device node. May be NULL. */
 	struct v4l2_ctrl_handler *ctrl_handler;
 
-	/* vb2_queue associated with this device node. May be NULL. */
 	struct vb2_queue *queue;
 
-	/* Priority state. If NULL, then v4l2_dev->prio will be used. */
 	struct v4l2_prio_state *prio;
 
 	/* device info */
 	char name[32];
-	int vfl_type;	/* device type */
-	int vfl_dir;	/* receiver, transmitter or m2m */
-	/* 'minor' is set to -1 if the registration failed */
+	int vfl_type;
+	int vfl_dir;
 	int minor;
 	u16 num;
-	/* use bitops to set/clear/test flags */
 	unsigned long flags;
-	/* attribute to differentiate multiple indices on one physical device */
 	int index;
 
 	/* V4L2 file handles */
-	spinlock_t		fh_lock; /* Lock for all v4l2_fhs */
-	struct list_head	fh_list; /* List of struct v4l2_fh */
+	spinlock_t		fh_lock;
+	struct list_head	fh_list;
 
-	/* Internal device debug flags, not for use by drivers */
 	int dev_debug;
 
-	/* Video standard vars */
-	v4l2_std_id tvnorms;		/* Supported tv norms */
+	v4l2_std_id tvnorms;
 
 	/* callbacks */
 	void (*release)(struct video_device *vdev);
-
-	/* ioctl callbacks */
 	const struct v4l2_ioctl_ops *ioctl_ops;
 	DECLARE_BITMAP(valid_ioctls, BASE_VIDIOC_PRIVATE);
 
-	/* serialization lock */
 	DECLARE_BITMAP(disable_locking, BASE_VIDIOC_PRIVATE);
 	struct mutex *lock;
 };
@@ -151,88 +264,241 @@ struct video_device
 /* dev to video-device */
 #define to_video_device(cd) container_of(cd, struct video_device, dev)
 
+/**
+ * __video_register_device - register video4linux devices
+ *
+ * @vdev: struct video_device to register
+ * @type: type of device to register
+ * @nr:   which device node number is desired:
+ * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
+ * @warn_if_nr_in_use: warn if the desired device node number
+ *        was already in use and another number was chosen instead.
+ * @owner: module that owns the video device node
+ *
+ * The registration code assigns minor numbers and device node numbers
+ * based on the requested type and registers the new device node with
+ * the kernel.
+ *
+ * This function assumes that struct video_device was zeroed when it
+ * was allocated and does not contain any stale date.
+ *
+ * An error is returned if no free minor or device node number could be
+ * found, or if the registration of the device node failed.
+ *
+ * Returns 0 on success.
+ *
+ * Valid values for @type are:
+ *
+ *	- %VFL_TYPE_GRABBER - A frame grabber
+ *	- %VFL_TYPE_VBI - Vertical blank data (undecoded)
+ *	- %VFL_TYPE_RADIO - A radio card
+ *	- %VFL_TYPE_SUBDEV - A subdevice
+ *	- %VFL_TYPE_SDR - Software Defined Radio
+ *
+ * .. note::
+ *
+ *	This function is meant to be used only inside the V4L2 core.
+ *	Drivers should use video_register_device() or
+ *	video_register_device_no_warn().
+ */
 int __must_check __video_register_device(struct video_device *vdev, int type,
 		int nr, int warn_if_nr_in_use, struct module *owner);
 
-/* Register video devices. Note that if video_register_device fails,
-   the release() callback of the video_device structure is *not* called, so
-   the caller is responsible for freeing any data. Usually that means that
-   you call video_device_release() on failure. */
+/**
+ *  video_register_device - register video4linux devices
+ *
+ * @vdev: struct video_device to register
+ * @type: type of device to register
+ * @nr:   which device node number is desired:
+ * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
+ *
+ * Internally, it calls __video_register_device(). Please see its
+ * documentation for more details.
+ *
+ * .. note::
+ * 	if video_register_device fails, the release() callback of
+ *	&struct video_device structure is *not* called, so the caller
+ *	is responsible for freeing any data. Usually that means that
+ *	you video_device_release() should be called on failure.
+ */
 static inline int __must_check video_register_device(struct video_device *vdev,
 		int type, int nr)
 {
 	return __video_register_device(vdev, type, nr, 1, vdev->fops->owner);
 }
 
-/* Same as video_register_device, but no warning is issued if the desired
-   device node number was already in use. */
+/**
+ *  video_register_device_no_warn - register video4linux devices
+ *
+ * @vdev: struct video_device to register
+ * @type: type of device to register
+ * @nr:   which device node number is desired:
+ * 	(0 == /dev/video0, 1 == /dev/video1, ..., -1 == first free)
+ *
+ * This function is identical to video_register_device() except that no
+ * warning is issued if the desired device node number was already in use.
+ *
+ * Internally, it calls __video_register_device(). Please see its
+ * documentation for more details.
+ *
+ * .. note::
+ * 	if video_register_device fails, the release() callback of
+ *	&struct video_device structure is *not* called, so the caller
+ *	is responsible for freeing any data. Usually that means that
+ *	you video_device_release() should be called on failure.
+ */
 static inline int __must_check video_register_device_no_warn(
 		struct video_device *vdev, int type, int nr)
 {
 	return __video_register_device(vdev, type, nr, 0, vdev->fops->owner);
 }
 
-/* Unregister video devices. Will do nothing if vdev == NULL or
-   video_is_registered() returns false. */
+/**
+ * video_unregister_device - Unregister video devices.
+ *
+ * @vdev: &struct video_device to register
+ *
+ * Does nothing if vdev == NULL or if video_is_registered() returns false.
+ */
 void video_unregister_device(struct video_device *vdev);
 
-/* helper functions to alloc/release struct video_device, the
-   latter can also be used for video_device->release(). */
+/**
+ * video_device_alloc - helper function to alloc &struct video_device
+ *
+ * Returns NULL if %-ENOMEM or a &struct video_device on success.
+ */
 struct video_device * __must_check video_device_alloc(void);
 
-/* this release function frees the vdev pointer */
+/**
+ * video_device_release - helper function to release &struct video_device
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * Can also be used for video_device->release\(\).
+ */
 void video_device_release(struct video_device *vdev);
 
-/* this release function does nothing, use when the video_device is a
-   static global struct. Note that having a static video_device is
-   a dubious construction at best. */
+/**
+ * video_device_release_empty - helper function to implement the
+ * 	video_device->release\(\) callback.
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * This release function does nothing.
+ *
+ * It should be used when the video_device is a static global struct.
+ *
+ * .. note::
+ *	Having a static video_device is a dubious construction at best.
+ */
 void video_device_release_empty(struct video_device *vdev);
 
-/* returns true if cmd is a known V4L2 ioctl */
+/**
+ * v4l2_is_known_ioctl - Checks if a given cmd is a known V4L ioctl
+ *
+ * @cmd: ioctl command
+ *
+ * returns true if cmd is a known V4L2 ioctl
+ */
 bool v4l2_is_known_ioctl(unsigned int cmd);
 
-/* mark that this command shouldn't use core locking */
-static inline void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd)
+/** v4l2_disable_ioctl_locking - mark that a given command
+ *	shouldn't use core locking
+ *
+ * @vdev: pointer to &struct video_device
+ * @cmd: ioctl command
+ */
+static inline void v4l2_disable_ioctl_locking(struct video_device *vdev,
+					      unsigned int cmd)
 {
 	if (_IOC_NR(cmd) < BASE_VIDIOC_PRIVATE)
 		set_bit(_IOC_NR(cmd), vdev->disable_locking);
 }
 
-/* Mark that this command isn't implemented. This must be called before
-   video_device_register. See also the comments in determine_valid_ioctls().
-   This function allows drivers to provide just one v4l2_ioctl_ops struct, but
-   disable ioctls based on the specific card that is actually found. */
-static inline void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd)
+/**
+ * v4l2_disable_ioctl- mark that a given command isn't implemented.
+ *	shouldn't use core locking
+ *
+ * @vdev: pointer to &struct video_device
+ * @cmd: ioctl command
+ *
+ * This function allows drivers to provide just one v4l2_ioctl_ops struct, but
+ * disable ioctls based on the specific card that is actually found.
+ *
+ * .. note::
+ *
+ *    This must be called before video_register_device.
+ *    See also the comments for determine_valid_ioctls().
+ */
+static inline void v4l2_disable_ioctl(struct video_device *vdev,
+				      unsigned int cmd)
 {
 	if (_IOC_NR(cmd) < BASE_VIDIOC_PRIVATE)
 		set_bit(_IOC_NR(cmd), vdev->valid_ioctls);
 }
 
-/* helper functions to access driver private data. */
+/**
+ * video_get_drvdata - gets private data from &struct video_device.
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * returns a pointer to the private data
+ */
 static inline void *video_get_drvdata(struct video_device *vdev)
 {
 	return dev_get_drvdata(&vdev->dev);
 }
 
+/**
+ * video_set_drvdata - sets private data from &struct video_device.
+ *
+ * @vdev: pointer to &struct video_device
+ * @data: private data pointer
+ */
 static inline void video_set_drvdata(struct video_device *vdev, void *data)
 {
 	dev_set_drvdata(&vdev->dev, data);
 }
 
+/**
+ * video_devdata - gets &struct video_device from struct file.
+ *
+ * @file: pointer to struct file
+ */
 struct video_device *video_devdata(struct file *file);
 
-/* Combine video_get_drvdata and video_devdata as this is
-   used very often. */
+/**
+ * video_drvdata - gets private data from &struct video_device using the
+ *	struct file.
+ *
+ * @file: pointer to struct file
+ *
+ * This is function combines both video_get_drvdata() and video_devdata()
+ * as this is used very often.
+ */
 static inline void *video_drvdata(struct file *file)
 {
 	return video_get_drvdata(video_devdata(file));
 }
 
+/**
+ * video_device_node_name - returns the video device name
+ *
+ * @vdev: pointer to &struct video_device
+ *
+ * Returns the device name string
+ */
 static inline const char *video_device_node_name(struct video_device *vdev)
 {
 	return dev_name(&vdev->dev);
 }
 
+/**
+ * video_is_registered - returns true if the &struct video_device is registered.
+ *
+ *
+ * @vdev: pointer to &struct video_device
+ */
 static inline int video_is_registered(struct video_device *vdev)
 {
 	return test_bit(V4L2_FL_REGISTERED, &vdev->flags);
diff --git a/include/media/v4l2-device.h b/include/media/v4l2-device.h
index d5d45a8d3998..a9d6aa41790e 100644
--- a/include/media/v4l2-device.h
+++ b/include/media/v4l2-device.h
@@ -25,100 +25,188 @@
 #include <media/v4l2-subdev.h>
 #include <media/v4l2-dev.h>
 
-/* Each instance of a V4L2 device should create the v4l2_device struct,
-   either stand-alone or embedded in a larger struct.
-
-   It allows easy access to sub-devices (see v4l2-subdev.h) and provides
-   basic V4L2 device-level support.
- */
-
 #define V4L2_DEVICE_NAME_SIZE (20 + 16)
 
 struct v4l2_ctrl_handler;
 
+/**
+ * struct v4l2_device - main struct to for V4L2 device drivers
+ *
+ * @dev: pointer to struct device.
+ * @mdev: pointer to struct media_device
+ * @subdevs: used to keep track of the registered subdevs
+ * @lock: lock this struct; can be used by the driver as well
+ *	if this struct is embedded into a larger struct.
+ * @name: unique device name, by default the driver name + bus ID
+ * @notify: notify callback called by some sub-devices.
+ * @ctrl_handler: The control handler. May be NULL.
+ * @prio: Device's priority state
+ * @ref: Keep track of the references to this struct.
+ * @release: Release function that is called when the ref count
+ *	goes to 0.
+ *
+ * Each instance of a V4L2 device should create the v4l2_device struct,
+ * either stand-alone or embedded in a larger struct.
+ *
+ * It allows easy access to sub-devices (see v4l2-subdev.h) and provides
+ * basic V4L2 device-level support.
+ *
+ * .. note::
+ *
+ *    #) dev->driver_data points to this struct.
+ *    #) dev might be NULL if there is no parent device
+ */
+
 struct v4l2_device {
-	/* dev->driver_data points to this struct.
-	   Note: dev might be NULL if there is no parent device
-	   as is the case with e.g. ISA devices. */
 	struct device *dev;
 #if defined(CONFIG_MEDIA_CONTROLLER)
 	struct media_device *mdev;
 #endif
-	/* used to keep track of the registered subdevs */
 	struct list_head subdevs;
-	/* lock this struct; can be used by the driver as well if this
-	   struct is embedded into a larger struct. */
 	spinlock_t lock;
-	/* unique device name, by default the driver name + bus ID */
 	char name[V4L2_DEVICE_NAME_SIZE];
-	/* notify callback called by some sub-devices. */
 	void (*notify)(struct v4l2_subdev *sd,
 			unsigned int notification, void *arg);
-	/* The control handler. May be NULL. */
 	struct v4l2_ctrl_handler *ctrl_handler;
-	/* Device's priority state */
 	struct v4l2_prio_state prio;
-	/* Keep track of the references to this struct. */
 	struct kref ref;
-	/* Release function that is called when the ref count goes to 0. */
 	void (*release)(struct v4l2_device *v4l2_dev);
 };
 
+/**
+ * v4l2_device_get - gets a V4L2 device reference
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * This is an ancillary routine meant to increment the usage for the
+ * struct v4l2_device pointed by @v4l2_dev.
+ */
 static inline void v4l2_device_get(struct v4l2_device *v4l2_dev)
 {
 	kref_get(&v4l2_dev->ref);
 }
 
+/**
+ * v4l2_device_put - putss a V4L2 device reference
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * This is an ancillary routine meant to decrement the usage for the
+ * struct v4l2_device pointed by @v4l2_dev.
+ */
 int v4l2_device_put(struct v4l2_device *v4l2_dev);
 
-/* Initialize v4l2_dev and make dev->driver_data point to v4l2_dev.
-   dev may be NULL in rare cases (ISA devices). In that case you
-   must fill in the v4l2_dev->name field before calling this function. */
-int __must_check v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
-
-/* Optional function to initialize the name field of struct v4l2_device using
-   the driver name and a driver-global atomic_t instance.
-   This function will increment the instance counter and returns the instance
-   value used in the name.
-
-   Example:
-
-   static atomic_t drv_instance = ATOMIC_INIT(0);
-
-   ...
-
-   instance = v4l2_device_set_name(&v4l2_dev, "foo", &drv_instance);
-
-   The first time this is called the name field will be set to foo0 and
-   this function returns 0. If the name ends with a digit (e.g. cx18),
-   then the name will be set to cx18-0 since cx180 looks really odd. */
+/**
+ * v4l2_device_register -Initialize v4l2_dev and make dev->driver_data
+ * 	point to v4l2_dev.
+ *
+ * @dev: pointer to struct device
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * .. note::
+ *	dev may be NULL in rare cases (ISA devices).
+ *	In such case the caller must fill in the v4l2_dev->name field
+ *	before calling this function.
+ */
+int __must_check v4l2_device_register(struct device *dev,
+				      struct v4l2_device *v4l2_dev);
+
+/**
+ * v4l2_device_set_name - Optional function to initialize the
+ * 	name field of struct v4l2_device
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ * @basename: base name for the device name
+ * @instance: pointer to a static atomic_t var with the instance usage for
+ * 	the device driver.
+ *
+ * v4l2_device_set_name() initializes the name field of struct v4l2_device
+ * using the driver name and a driver-global atomic_t instance.
+ *
+ * This function will increment the instance counter and returns the
+ * instance value used in the name.
+ *
+ * Example:
+ *
+ *   static atomic_t drv_instance = ATOMIC_INIT(0);
+ *
+ *   ...
+ *
+ *   instance = v4l2_device_set_name(&v4l2_dev, "foo", &drv_instance);
+ *
+ * The first time this is called the name field will be set to foo0 and
+ * this function returns 0. If the name ends with a digit (e.g. cx18),
+ * then the name will be set to cx18-0 since cx180 would look really odd.
+ */
 int v4l2_device_set_name(struct v4l2_device *v4l2_dev, const char *basename,
-						atomic_t *instance);
-
-/* Set v4l2_dev->dev to NULL. Call when the USB parent disconnects.
-   Since the parent disappears this ensures that v4l2_dev doesn't have an
-   invalid parent pointer. */
+			 atomic_t *instance);
+
+/**
+ * v4l2_device_disconnect - Change V4L2 device state to disconnected.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ *
+ * Should be called when the USB parent disconnects.
+ * Since the parent disappears, this ensures that v4l2_dev doesn't have
+ * an invalid parent pointer.
+ *
+ * .. note:: This function sets v4l2_dev->dev to NULL.
+ */
 void v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
 
-/* Unregister all sub-devices and any other resources related to v4l2_dev. */
+/**
+ *  v4l2_device_unregister - Unregister all sub-devices and any other
+ *	 resources related to v4l2_dev.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ */
 void v4l2_device_unregister(struct v4l2_device *v4l2_dev);
 
-/* Register a subdev with a v4l2 device. While registered the subdev module
-   is marked as in-use. An error is returned if the module is no longer
-   loaded when you attempt to register it. */
+/**
+ * v4l2_device_register_subdev - Registers a subdev with a v4l2 device.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
+ * @sd: pointer to struct v4l2_subdev
+ *
+ * While registered, the subdev module is marked as in-use.
+ *
+ * An error is returned if the module is no longer loaded on any attempts
+ * to register it.
+ */
 int __must_check v4l2_device_register_subdev(struct v4l2_device *v4l2_dev,
-						struct v4l2_subdev *sd);
-/* Unregister a subdev with a v4l2 device. Can also be called if the subdev
-   wasn't registered. In that case it will do nothing. */
+					     struct v4l2_subdev *sd);
+
+/**
+ * v4l2_device_unregister_subdev - Unregisters a subdev with a v4l2 device.
+ *
+ * @sd: pointer to struct v4l2_subdev
+ *
+ * .. note ::
+ *
+ *	Can also be called if the subdev wasn't registered. In such
+ *	case, it will do nothing.
+ */
 void v4l2_device_unregister_subdev(struct v4l2_subdev *sd);
 
-/* Register device nodes for all subdev of the v4l2 device that are marked with
- * the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
+/**
+ * v4l2_device_register_subdev_nodes - Registers device nodes for all subdevs
+ *	of the v4l2 device that are marked with
+ * 	the V4L2_SUBDEV_FL_HAS_DEVNODE flag.
+ *
+ * @v4l2_dev: pointer to struct v4l2_device
  */
 int __must_check
 v4l2_device_register_subdev_nodes(struct v4l2_device *v4l2_dev);
 
-/* Send a notification to v4l2_device. */
+/**
+ * v4l2_subdev_notify - Sends a notification to v4l2_device.
+ *
+ * @sd: pointer to struct v4l2_subdev
+ * @notification: type of notification. Please notice that the notification
+ * 	type is driver-specific.
+ * @arg: arguments for the notification. Those are specific to each
+ *	notification type.
+ */
 static inline void v4l2_subdev_notify(struct v4l2_subdev *sd,
 				      unsigned int notification, void *arg)
 {
diff --git a/include/media/v4l2-dv-timings.h b/include/media/v4l2-dv-timings.h
index 1113c8874c26..65caadf13eec 100644
--- a/include/media/v4l2-dv-timings.h
+++ b/include/media/v4l2-dv-timings.h
@@ -28,7 +28,7 @@
  */
 extern const struct v4l2_dv_timings v4l2_dv_timings_presets[];
 
-/**
+/*
  * v4l2_check_dv_timings_fnc - timings check callback
  *
  * @t: the v4l2_dv_timings struct.
diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h
index 9792f906423b..ca854203b8b9 100644
--- a/include/media/v4l2-event.h
+++ b/include/media/v4l2-event.h
@@ -73,14 +73,15 @@ struct video_device;
  * @list:	List node for the v4l2_fh->available list.
  * @sev:	Pointer to parent v4l2_subscribed_event.
  * @event:	The event itself.
-  */
+ */
 struct v4l2_kevent {
 	struct list_head	list;
 	struct v4l2_subscribed_event *sev;
 	struct v4l2_event	event;
 };
 
-/** struct v4l2_subscribed_event_ops - Subscribed event operations.
+/**
+ * struct v4l2_subscribed_event_ops - Subscribed event operations.
  *
  * @add:	Optional callback, called when a new listener is added
  * @del:	Optional callback, called when a listener stops listening
@@ -88,20 +89,23 @@ struct v4l2_kevent {
  * @merge:	Optional callback that can merge event 'old' into event 'new'.
  */
 struct v4l2_subscribed_event_ops {
-	int  (*add)(struct v4l2_subscribed_event *sev, unsigned elems);
+	int  (*add)(struct v4l2_subscribed_event *sev, unsigned int elems);
 	void (*del)(struct v4l2_subscribed_event *sev);
 	void (*replace)(struct v4l2_event *old, const struct v4l2_event *new);
 	void (*merge)(const struct v4l2_event *old, struct v4l2_event *new);
 };
 
 /**
- * struct v4l2_subscribed_event - Internal struct representing a subscribed event.
+ * struct v4l2_subscribed_event - Internal struct representing a subscribed
+ *		event.
+ *
  * @list:	List node for the v4l2_fh->subscribed list.
  * @type:	Event type.
  * @id:	Associated object ID (e.g. control ID). 0 if there isn't any.
  * @flags:	Copy of v4l2_event_subscription->flags.
  * @fh:	Filehandle that subscribed to this event.
- * @node:	List node that hooks into the object's event list (if there is one).
+ * @node:	List node that hooks into the object's event list
+ *		(if there is one).
  * @ops:	v4l2_subscribed_event_ops
  * @elems:	The number of elements in the events array.
  * @first:	The index of the events containing the oldest available event.
@@ -116,27 +120,124 @@ struct v4l2_subscribed_event {
 	struct v4l2_fh		*fh;
 	struct list_head	node;
 	const struct v4l2_subscribed_event_ops *ops;
-	unsigned		elems;
-	unsigned		first;
-	unsigned		in_use;
+	unsigned int		elems;
+	unsigned int		first;
+	unsigned int		in_use;
 	struct v4l2_kevent	events[];
 };
 
+/**
+ * v4l2_event_dequeue - Dequeue events from video device.
+ *
+ * @fh: pointer to struct v4l2_fh
+ * @event: pointer to struct v4l2_event
+ * @nonblocking: if not zero, waits for an event to arrive
+ */
 int v4l2_event_dequeue(struct v4l2_fh *fh, struct v4l2_event *event,
 		       int nonblocking);
+
+/**
+ * v4l2_event_queue - Queue events to video device.
+ *
+ * @vdev: pointer to &struct video_device
+ * @ev: pointer to &struct v4l2_event
+ *
+ * The event will be queued for all &struct v4l2_fh file handlers.
+ *
+ * .. note::
+ *    The driver's only responsibility is to fill in the type and the data
+ *    fields.The other fields will be filled in by  V4L2.
+ */
 void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev);
+
+/**
+ * v4l2_event_queue_fh - Queue events to video device.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @ev: pointer to &struct v4l2_event
+ *
+ *
+ * The event will be queued only for the specified &struct v4l2_fh file handler.
+ *
+ * .. note::
+ *    The driver's only responsibility is to fill in the type and the data
+ *    fields.The other fields will be filled in by  V4L2.
+ */
 void v4l2_event_queue_fh(struct v4l2_fh *fh, const struct v4l2_event *ev);
+
+/**
+ * v4l2_event_pending - Check if an event is available
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * Returns the number of pending events.
+ */
 int v4l2_event_pending(struct v4l2_fh *fh);
+
+/**
+ * v4l2_event_subscribe - Subscribes to an event
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ * @elems: size of the events queue
+ * @ops: pointer to &v4l2_subscribed_event_ops
+ *
+ * .. note::
+ *
+ *    if @elems is zero, the framework will fill in a default value,
+ *    with is currently 1 element.
+ */
 int v4l2_event_subscribe(struct v4l2_fh *fh,
-			 const struct v4l2_event_subscription *sub, unsigned elems,
+			 const struct v4l2_event_subscription *sub,
+			 unsigned int elems,
 			 const struct v4l2_subscribed_event_ops *ops);
+/**
+ * v4l2_event_unsubscribe - Unsubscribes to an event
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ */
 int v4l2_event_unsubscribe(struct v4l2_fh *fh,
 			   const struct v4l2_event_subscription *sub);
+/**
+ * v4l2_event_unsubscribe_all - Unsubscribes to all events
+ *
+ * @fh: pointer to &struct v4l2_fh
+ */
 void v4l2_event_unsubscribe_all(struct v4l2_fh *fh);
-int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd, struct v4l2_fh *fh,
+
+/**
+ * v4l2_event_subdev_unsubscribe - Subdev variant of v4l2_event_unsubscribe()
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ *
+ * .. note::
+ *
+ *	This function should be used for the &struct v4l2_subdev_core_ops
+ *	%unsubscribe_event field.
+ */
+int v4l2_event_subdev_unsubscribe(struct v4l2_subdev *sd,
+				  struct v4l2_fh *fh,
 				  struct v4l2_event_subscription *sub);
+/**
+ * v4l2_src_change_event_subscribe -
+ *
+ * @fh: pointer to struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ */
 int v4l2_src_change_event_subscribe(struct v4l2_fh *fh,
-				const struct v4l2_event_subscription *sub);
+				    const struct v4l2_event_subscription *sub);
+/**
+ * v4l2_src_change_event_subdev_subscribe - Variant of v4l2_event_subscribe(),
+ *	meant to subscribe only events of the type %V4L2_EVENT_SOURCE_CHANGE.
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @fh: pointer to &struct v4l2_fh
+ * @sub: pointer to &struct v4l2_event_subscription
+ */
 int v4l2_src_change_event_subdev_subscribe(struct v4l2_subdev *sd,
-		struct v4l2_fh *fh, struct v4l2_event_subscription *sub);
+					   struct v4l2_fh *fh,
+					   struct v4l2_event_subscription *sub);
 #endif /* V4L2_EVENT_H */
diff --git a/include/media/v4l2-fh.h b/include/media/v4l2-fh.h
index 803516775162..e19e6246e21c 100644
--- a/include/media/v4l2-fh.h
+++ b/include/media/v4l2-fh.h
@@ -33,6 +33,21 @@
 struct video_device;
 struct v4l2_ctrl_handler;
 
+/**
+ * struct v4l2_fh - Describes a V4L2 file handler
+ *
+ * @list: list of file handlers
+ * @vdev: pointer to &struct video_device
+ * @ctrl_handler: pointer to &struct v4l2_ctrl_handler
+ * @prio: priority of the file handler, as defined by &enum v4l2_priority
+ *
+ * @wait: event' s wait queue
+ * @subscribed: list of subscribed events
+ * @available: list of events waiting to be dequeued
+ * @navailable: number of available events at @available list
+ * @sequence: event sequence number
+ * @m2m_ctx: pointer to &struct v4l2_m2m_ctx
+ */
 struct v4l2_fh {
 	struct list_head	list;
 	struct video_device	*vdev;
@@ -41,8 +56,8 @@ struct v4l2_fh {
 
 	/* Events */
 	wait_queue_head_t	wait;
-	struct list_head	subscribed; /* Subscribed events */
-	struct list_head	available; /* Dequeueable event */
+	struct list_head	subscribed;
+	struct list_head	available;
 	unsigned int		navailable;
 	u32			sequence;
 
@@ -51,53 +66,102 @@ struct v4l2_fh {
 #endif
 };
 
-/*
- * Initialise the file handle. Parts of the V4L2 framework using the
+/**
+ * v4l2_fh_init - Initialise the file handle.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ * @vdev: pointer to &struct video_device
+ *
+ * Parts of the V4L2 framework using the
  * file handles should be initialised in this function. Must be called
- * from driver's v4l2_file_operations->open() handler if the driver
- * uses v4l2_fh.
+ * from driver's v4l2_file_operations->open\(\) handler if the driver
+ * uses &struct v4l2_fh.
  */
 void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev);
-/*
- * Add the fh to the list of file handles on a video_device. The file
- * handle must be initialised first.
+
+/**
+ * v4l2_fh_add - Add the fh to the list of file handles on a video_device.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * .. note::
+ *    The @fh file handle must be initialised first.
  */
 void v4l2_fh_add(struct v4l2_fh *fh);
-/*
- * Can be used as the open() op of v4l2_file_operations.
- * It allocates a v4l2_fh and inits and adds it to the video_device associated
- * with the file pointer.
+
+/**
+ * v4l2_fh_open - Ancillary routine that can be used as the open\(\) op
+ *	of v4l2_file_operations.
+ *
+ * @filp: pointer to struct file
+ *
+ * It allocates a v4l2_fh and inits and adds it to the &struct video_device
+ * associated with the file pointer.
  */
 int v4l2_fh_open(struct file *filp);
-/*
- * Remove file handle from the list of file handles. Must be called in
- * v4l2_file_operations->release() handler if the driver uses v4l2_fh.
- * On error filp->private_data will be NULL, otherwise it will point to
- * the v4l2_fh struct.
+
+/**
+ * v4l2_fh_del - Remove file handle from the list of file handles.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * On error filp->private_data will be %NULL, otherwise it will point to
+ * the &struct v4l2_fh.
+ *
+ * .. note::
+ *    Must be called in v4l2_file_operations->release\(\) handler if the driver
+ *    uses &struct v4l2_fh.
  */
 void v4l2_fh_del(struct v4l2_fh *fh);
-/*
- * Release resources related to a file handle. Parts of the V4L2
- * framework using the v4l2_fh must release their resources here, too.
- * Must be called in v4l2_file_operations->release() handler if the
- * driver uses v4l2_fh.
+
+/**
+ * v4l2_fh_exit - Release resources related to a file handle.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * Parts of the V4L2 framework using the v4l2_fh must release their
+ * resources here, too.
+ *
+ * .. note::
+ *    Must be called in v4l2_file_operations->release\(\) handler if the
+ *    driver uses &struct v4l2_fh.
  */
 void v4l2_fh_exit(struct v4l2_fh *fh);
-/*
- * Can be used as the release() op of v4l2_file_operations.
+
+/**
+ * v4l2_fh_release - Ancillary routine that can be used as the release\(\) op
+ *	of v4l2_file_operations.
+ *
+ * @filp: pointer to struct file
+ *
  * It deletes and exits the v4l2_fh associated with the file pointer and
  * frees it. It will do nothing if filp->private_data (the pointer to the
- * v4l2_fh struct) is NULL. This function always returns 0.
+ * v4l2_fh struct) is %NULL.
+ *
+ * This function always returns 0.
  */
 int v4l2_fh_release(struct file *filp);
-/*
- * Returns 1 if this filehandle is the only filehandle opened for the
- * associated video_device. If fh is NULL, then it returns 0.
+
+/**
+ * v4l2_fh_is_singular - Returns 1 if this filehandle is the only filehandle
+ *	 opened for the associated video_device.
+ *
+ * @fh: pointer to &struct v4l2_fh
+ *
+ * If @fh is NULL, then it returns 0.
  */
 int v4l2_fh_is_singular(struct v4l2_fh *fh);
-/*
- * Helper function with struct file as argument. If filp->private_data is
- * NULL, then it will return 0.
+
+/**
+ * v4l2_fh_is_singular_file - Returns 1 if this filehandle is the only
+ *	filehandle opened for the associated video_device.
+ *
+ * @filp: pointer to struct file
+ *
+ * This is a helper function variant of v4l2_fh_is_singular() with uses
+ * struct file as argument.
+ *
+ * If filp->private_data is %NULL, then it will return 0.
  */
 static inline int v4l2_fh_is_singular_file(struct file *filp)
 {
diff --git a/include/media/v4l2-ioctl.h b/include/media/v4l2-ioctl.h
index 017ffb2220c7..8b1d19bc9b0e 100644
--- a/include/media/v4l2-ioctl.h
+++ b/include/media/v4l2-ioctl.h
@@ -17,6 +17,272 @@
 
 struct v4l2_fh;
 
+/**
+ * struct v4l2_ioctl_ops - describe operations for each V4L2 ioctl
+ *
+ * @vidioc_querycap: pointer to the function that implements
+ *	:ref:`VIDIOC_QUERYCAP <vidioc_querycap>` ioctl
+ * @vidioc_enum_fmt_vid_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ *	for video capture in single plane mode
+ * @vidioc_enum_fmt_vid_overlay: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ *	for video overlay
+ * @vidioc_enum_fmt_vid_out: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ *	for video output in single plane mode
+ * @vidioc_enum_fmt_vid_cap_mplane: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ *	for video capture in multiplane mode
+ * @vidioc_enum_fmt_vid_out_mplane: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ *	for video output in multiplane mode
+ * @vidioc_enum_fmt_sdr_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ *	for Software Defined Radio capture
+ * @vidioc_enum_fmt_sdr_out: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_FMT <vidioc_enum_fmt>` ioctl logic
+ *	for Software Defined Radio output
+ * @vidioc_g_fmt_vid_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ *	in single plane mode
+ * @vidioc_g_fmt_vid_overlay: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video overlay
+ * @vidioc_g_fmt_vid_out: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video out
+ *	in single plane mode
+ * @vidioc_g_fmt_vid_out_overlay: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video overlay output
+ * @vidioc_g_fmt_vbi_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for raw VBI capture
+ * @vidioc_g_fmt_vbi_out: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for raw VBI output
+ * @vidioc_g_fmt_sliced_vbi_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI capture
+ * @vidioc_g_fmt_sliced_vbi_out: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI output
+ * @vidioc_g_fmt_vid_cap_mplane: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ *	in multiple plane mode
+ * @vidioc_g_fmt_vid_out_mplane: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video out
+ *	in multiplane plane mode
+ * @vidioc_g_fmt_sdr_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ *	Radio capture
+ * @vidioc_g_fmt_sdr_out: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ *	Radio output
+ * @vidioc_s_fmt_vid_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ *	in single plane mode
+ * @vidioc_s_fmt_vid_overlay: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video overlay
+ * @vidioc_s_fmt_vid_out: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video out
+ *	in single plane mode
+ * @vidioc_s_fmt_vid_out_overlay: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video overlay output
+ * @vidioc_s_fmt_vbi_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for raw VBI capture
+ * @vidioc_s_fmt_vbi_out: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for raw VBI output
+ * @vidioc_s_fmt_sliced_vbi_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI capture
+ * @vidioc_s_fmt_sliced_vbi_out: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI output
+ * @vidioc_s_fmt_vid_cap_mplane: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ *	in multiple plane mode
+ * @vidioc_s_fmt_vid_out_mplane: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video out
+ *	in multiplane plane mode
+ * @vidioc_s_fmt_sdr_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ *	Radio capture
+ * @vidioc_s_fmt_sdr_out: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ *	Radio output
+ * @vidioc_try_fmt_vid_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ *	in single plane mode
+ * @vidioc_try_fmt_vid_overlay: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video overlay
+ * @vidioc_try_fmt_vid_out: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video out
+ *	in single plane mode
+ * @vidioc_try_fmt_vid_out_overlay: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video overlay
+ *	output
+ * @vidioc_try_fmt_vbi_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for raw VBI capture
+ * @vidioc_try_fmt_vbi_out: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for raw VBI output
+ * @vidioc_try_fmt_sliced_vbi_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI
+ *	capture
+ * @vidioc_try_fmt_sliced_vbi_out: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for sliced VBI output
+ * @vidioc_try_fmt_vid_cap_mplane: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video capture
+ *	in multiple plane mode
+ * @vidioc_try_fmt_vid_out_mplane: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video out
+ *	in multiplane plane mode
+ * @vidioc_try_fmt_sdr_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ *	Radio capture
+ * @vidioc_try_fmt_sdr_out: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for Software Defined
+ *	Radio output
+ * @vidioc_reqbufs: pointer to the function that implements
+ *	:ref:`VIDIOC_REQBUFS <vidioc_reqbufs>` ioctl
+ * @vidioc_querybuf: pointer to the function that implements
+ *	:ref:`VIDIOC_QUERYBUF <vidioc_querybuf>` ioctl
+ * @vidioc_qbuf: pointer to the function that implements
+ *	:ref:`VIDIOC_QBUF <vidioc_qbuf>` ioctl
+ * @vidioc_expbuf: pointer to the function that implements
+ *	:ref:`VIDIOC_EXPBUF <vidioc_expbuf>` ioctl
+ * @vidioc_dqbuf: pointer to the function that implements
+ *	:ref:`VIDIOC_DQBUF <vidioc_qbuf>` ioctl
+ * @vidioc_create_bufs: pointer to the function that implements
+ *	:ref:`VIDIOC_CREATE_BUFS <vidioc_create_bufs>` ioctl
+ * @vidioc_prepare_buf: pointer to the function that implements
+ *	:ref:`VIDIOC_PREPARE_BUF <vidioc_prepare_buf>` ioctl
+ * @vidioc_overlay: pointer to the function that implements
+ *	:ref:`VIDIOC_OVERLAY <vidioc_overlay>` ioctl
+ * @vidioc_g_fbuf: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FBUF <vidioc_g_fbuf>` ioctl
+ * @vidioc_s_fbuf: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FBUF <vidioc_g_fbuf>` ioctl
+ * @vidioc_streamon: pointer to the function that implements
+ *	:ref:`VIDIOC_STREAMON <vidioc_streamon>` ioctl
+ * @vidioc_streamoff: pointer to the function that implements
+ *	:ref:`VIDIOC_STREAMOFF <vidioc_streamon>` ioctl
+ * @vidioc_g_std: pointer to the function that implements
+ *	:ref:`VIDIOC_G_STD <vidioc_g_std>` ioctl
+ * @vidioc_s_std: pointer to the function that implements
+ *	:ref:`VIDIOC_S_STD <vidioc_g_std>` ioctl
+ * @vidioc_querystd: pointer to the function that implements
+ *	:ref:`VIDIOC_QUERYSTD <vidioc_querystd>` ioctl
+ * @vidioc_enum_input: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_INPUT <vidioc_g_input>` ioctl
+ * @vidioc_g_input: pointer to the function that implements
+ *	:ref:`VIDIOC_G_INPUT <vidioc_g_input>` ioctl
+ * @vidioc_s_input: pointer to the function that implements
+ *	:ref:`VIDIOC_S_INPUT <vidioc_g_input>` ioctl
+ * @vidioc_enum_output: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_OUTPUT <vidioc_g_output>` ioctl
+ * @vidioc_g_output: pointer to the function that implements
+ *	:ref:`VIDIOC_G_OUTPUT <vidioc_g_output>` ioctl
+ * @vidioc_s_output: pointer to the function that implements
+ *	:ref:`VIDIOC_S_OUTPUT <vidioc_g_output>` ioctl
+ * @vidioc_queryctrl: pointer to the function that implements
+ *	:ref:`VIDIOC_QUERYCTRL <vidioc_queryctrl>` ioctl
+ * @vidioc_query_ext_ctrl: pointer to the function that implements
+ *	:ref:`VIDIOC_QUERY_EXT_CTRL <vidioc_queryctrl>` ioctl
+ * @vidioc_g_ctrl: pointer to the function that implements
+ *	:ref:`VIDIOC_G_CTRL <vidioc_g_ctrl>` ioctl
+ * @vidioc_s_ctrl: pointer to the function that implements
+ *	:ref:`VIDIOC_S_CTRL <vidioc_g_ctrl>` ioctl
+ * @vidioc_g_ext_ctrls: pointer to the function that implements
+ *	:ref:`VIDIOC_G_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ * @vidioc_s_ext_ctrls: pointer to the function that implements
+ *	:ref:`VIDIOC_S_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ * @vidioc_try_ext_ctrls: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_EXT_CTRLS <vidioc_g_ext_ctrls>` ioctl
+ * @vidioc_querymenu: pointer to the function that implements
+ *	:ref:`VIDIOC_QUERYMENU <vidioc_queryctrl>` ioctl
+ * @vidioc_enumaudio: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUMAUDIO <vidioc_enumaudio>` ioctl
+ * @vidioc_g_audio: pointer to the function that implements
+ *	:ref:`VIDIOC_G_AUDIO <vidioc_g_audio>` ioctl
+ * @vidioc_s_audio: pointer to the function that implements
+ *	:ref:`VIDIOC_S_AUDIO <vidioc_g_audio>` ioctl
+ * @vidioc_enumaudout: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUMAUDOUT <vidioc_enumaudout>` ioctl
+ * @vidioc_g_audout: pointer to the function that implements
+ *	:ref:`VIDIOC_G_AUDOUT <vidioc_g_audout>` ioctl
+ * @vidioc_s_audout: pointer to the function that implements
+ *	:ref:`VIDIOC_S_AUDOUT <vidioc_g_audout>` ioctl
+ * @vidioc_g_modulator: pointer to the function that implements
+ *	:ref:`VIDIOC_G_MODULATOR <vidioc_g_modulator>` ioctl
+ * @vidioc_s_modulator: pointer to the function that implements
+ *	:ref:`VIDIOC_S_MODULATOR <vidioc_g_modulator>` ioctl
+ * @vidioc_cropcap: pointer to the function that implements
+ *	:ref:`VIDIOC_CROPCAP <vidioc_cropcap>` ioctl
+ * @vidioc_g_crop: pointer to the function that implements
+ *	:ref:`VIDIOC_G_CROP <vidioc_g_crop>` ioctl
+ * @vidioc_s_crop: pointer to the function that implements
+ *	:ref:`VIDIOC_S_CROP <vidioc_g_crop>` ioctl
+ * @vidioc_g_selection: pointer to the function that implements
+ *	:ref:`VIDIOC_G_SELECTION <vidioc_g_selection>` ioctl
+ * @vidioc_s_selection: pointer to the function that implements
+ *	:ref:`VIDIOC_S_SELECTION <vidioc_g_selection>` ioctl
+ * @vidioc_g_jpegcomp: pointer to the function that implements
+ *	:ref:`VIDIOC_G_JPEGCOMP <vidioc_g_jpegcomp>` ioctl
+ * @vidioc_s_jpegcomp: pointer to the function that implements
+ *	:ref:`VIDIOC_S_JPEGCOMP <vidioc_g_jpegcomp>` ioctl
+ * @vidioc_g_enc_index: pointer to the function that implements
+ *	:ref:`VIDIOC_G_ENC_INDEX <vidioc_g_enc_index>` ioctl
+ * @vidioc_encoder_cmd: pointer to the function that implements
+ *	:ref:`VIDIOC_ENCODER_CMD <vidioc_encoder_cmd>` ioctl
+ * @vidioc_try_encoder_cmd: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_ENCODER_CMD <vidioc_encoder_cmd>` ioctl
+ * @vidioc_decoder_cmd: pointer to the function that implements
+ *	:ref:`VIDIOC_DECODER_CMD <vidioc_decoder_cmd>` ioctl
+ * @vidioc_try_decoder_cmd: pointer to the function that implements
+ *	:ref:`VIDIOC_TRY_DECODER_CMD <vidioc_decoder_cmd>` ioctl
+ * @vidioc_g_parm: pointer to the function that implements
+ *	:ref:`VIDIOC_G_PARM <vidioc_g_parm>` ioctl
+ * @vidioc_s_parm: pointer to the function that implements
+ *	:ref:`VIDIOC_S_PARM <vidioc_g_parm>` ioctl
+ * @vidioc_g_tuner: pointer to the function that implements
+ *	:ref:`VIDIOC_G_TUNER <vidioc_g_tuner>` ioctl
+ * @vidioc_s_tuner: pointer to the function that implements
+ *	:ref:`VIDIOC_S_TUNER <vidioc_g_tuner>` ioctl
+ * @vidioc_g_frequency: pointer to the function that implements
+ *	:ref:`VIDIOC_G_FREQUENCY <vidioc_g_frequency>` ioctl
+ * @vidioc_s_frequency: pointer to the function that implements
+ *	:ref:`VIDIOC_S_FREQUENCY <vidioc_g_frequency>` ioctl
+ * @vidioc_enum_freq_bands: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_FREQ_BANDS <vidioc_enum_freq_bands>` ioctl
+ * @vidioc_g_sliced_vbi_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_G_SLICED_VBI_CAP <vidioc_g_sliced_vbi_cap>` ioctl
+ * @vidioc_log_status: pointer to the function that implements
+ *	:ref:`VIDIOC_LOG_STATUS <vidioc_log_status>` ioctl
+ * @vidioc_s_hw_freq_seek: pointer to the function that implements
+ *	:ref:`VIDIOC_S_HW_FREQ_SEEK <vidioc_s_hw_freq_seek>` ioctl
+ * @vidioc_g_register: pointer to the function that implements
+ *	:ref:`VIDIOC_DBG_G_REGISTER <vidioc_dbg_g_register>` ioctl
+ * @vidioc_s_register: pointer to the function that implements
+ *	:ref:`VIDIOC_DBG_S_REGISTER <vidioc_dbg_g_register>` ioctl
+ * @vidioc_g_chip_info: pointer to the function that implements
+ *	:ref:`VIDIOC_DBG_G_CHIP_INFO <vidioc_dbg_g_chip_info>` ioctl
+ * @vidioc_enum_framesizes: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_FRAMESIZES <vidioc_enum_framesizes>` ioctl
+ * @vidioc_enum_frameintervals: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_FRAMEINTERVALS <vidioc_enum_frameintervals>` ioctl
+ * @vidioc_s_dv_timings: pointer to the function that implements
+ *	:ref:`VIDIOC_S_DV_TIMINGS <vidioc_g_dv_timings>` ioctl
+ * @vidioc_g_dv_timings: pointer to the function that implements
+ *	:ref:`VIDIOC_G_DV_TIMINGS <vidioc_g_dv_timings>` ioctl
+ * @vidioc_query_dv_timings: pointer to the function that implements
+ *	:ref:`VIDIOC_QUERY_DV_TIMINGS <vidioc_query_dv_timings>` ioctl
+ * @vidioc_enum_dv_timings: pointer to the function that implements
+ *	:ref:`VIDIOC_ENUM_DV_TIMINGS <vidioc_enum_dv_timings>` ioctl
+ * @vidioc_dv_timings_cap: pointer to the function that implements
+ *	:ref:`VIDIOC_DV_TIMINGS_CAP <vidioc_dv_timings_cap>` ioctl
+ * @vidioc_g_edid: pointer to the function that implements
+ *	:ref:`VIDIOC_G_EDID <vidioc_g_edid>` ioctl
+ * @vidioc_s_edid: pointer to the function that implements
+ *	:ref:`VIDIOC_S_EDID <vidioc_g_edid>` ioctl
+ * @vidioc_subscribe_event: pointer to the function that implements
+ *	:ref:`VIDIOC_SUBSCRIBE_EVENT <vidioc_subscribe_event>` ioctl
+ * @vidioc_unsubscribe_event: pointer to the function that implements
+ *	:ref:`VIDIOC_UNSUBSCRIBE_EVENT <vidioc_unsubscribe_event>` ioctl
+ * @vidioc_default: pointed used to allow other ioctls
+ */
 struct v4l2_ioctl_ops {
 	/* ioctl callbacks */
 
diff --git a/include/media/v4l2-mc.h b/include/media/v4l2-mc.h
index 7a8d6037a4bb..28c3f9d9c209 100644
--- a/include/media/v4l2-mc.h
+++ b/include/media/v4l2-mc.h
@@ -114,11 +114,14 @@ struct usb_device;
  * Add links between the entities commonly found on PC customer's hardware at
  * the V4L2 side: camera sensors, audio and video PLL-IF decoders, tuners,
  * analog TV decoder and I/O entities (video, VBI and Software Defined Radio).
- * NOTE: webcams are modelled on a very simple way: the sensor is
- * connected directly to the I/O entity. All dirty details, like
- * scaler and crop HW are hidden. While such mapping is enough for v4l2
- * interface centric PC-consumer's hardware, V4L2 subdev centric camera
- * hardware should not use this routine, as it will not build the right graph.
+ *
+ * .. note::
+ *
+ *    Webcams are modelled on a very simple way: the sensor is
+ *    connected directly to the I/O entity. All dirty details, like
+ *    scaler and crop HW are hidden. While such mapping is enough for v4l2
+ *    interface centric PC-consumer's hardware, V4L2 subdev centric camera
+ *    hardware should not use this routine, as it will not build the right graph.
  */
 int v4l2_mc_create_media_graph(struct media_device *mdev);
 
diff --git a/include/media/v4l2-subdev.h b/include/media/v4l2-subdev.h
index c672efc4f87b..2a2240c99b30 100644
--- a/include/media/v4l2-subdev.h
+++ b/include/media/v4l2-subdev.h
@@ -1,21 +1,17 @@
 /*
-    V4L2 sub-device support header.
-
-    Copyright (C) 2008  Hans Verkuil <hverkuil@xs4all.nl>
-
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software
-    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ *  V4L2 sub-device support header.
+ *
+ *  Copyright (C) 2008  Hans Verkuil <hverkuil@xs4all.nl>
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
  */
 
 #ifndef _V4L2_SUBDEV_H
@@ -52,55 +48,64 @@ struct v4l2_subdev_fh;
 struct tuner_setup;
 struct v4l2_mbus_frame_desc;
 
-/* decode_vbi_line */
+/**
+ * struct v4l2_decode_vbi_line - used to decode_vbi_line
+ *
+ * @is_second_field: Set to 0 for the first (odd) field;
+ *	set to 1 for the second (even) field.
+ * @p: Pointer to the sliced VBI data from the decoder. On exit, points to
+ *	the start of the payload.
+ * @line: Line number of the sliced VBI data (1-23)
+ * @type: VBI service type (V4L2_SLICED_*). 0 if no service found
+ */
 struct v4l2_decode_vbi_line {
-	u32 is_second_field;	/* Set to 0 for the first (odd) field,
-				   set to 1 for the second (even) field. */
-	u8 *p; 			/* Pointer to the sliced VBI data from the decoder.
-				   On exit points to the start of the payload. */
-	u32 line;		/* Line number of the sliced VBI data (1-23) */
-	u32 type;		/* VBI service type (V4L2_SLICED_*). 0 if no service found */
+	u32 is_second_field;
+	u8 *p;
+	u32 line;
+	u32 type;
 };
 
-/* Sub-devices are devices that are connected somehow to the main bridge
-   device. These devices are usually audio/video muxers/encoders/decoders or
-   sensors and webcam controllers.
-
-   Usually these devices are controlled through an i2c bus, but other busses
-   may also be used.
-
-   The v4l2_subdev struct provides a way of accessing these devices in a
-   generic manner. Most operations that these sub-devices support fall in
-   a few categories: core ops, audio ops, video ops and tuner ops.
-
-   More categories can be added if needed, although this should remain a
-   limited set (no more than approx. 8 categories).
-
-   Each category has its own set of ops that subdev drivers can implement.
-
-   A subdev driver can leave the pointer to the category ops NULL if
-   it does not implement them (e.g. an audio subdev will generally not
-   implement the video category ops). The exception is the core category:
-   this must always be present.
-
-   These ops are all used internally so it is no problem to change, remove
-   or add ops or move ops from one to another category. Currently these
-   ops are based on the original ioctls, but since ops are not limited to
-   one argument there is room for improvement here once all i2c subdev
-   drivers are converted to use these ops.
+/*
+ * Sub-devices are devices that are connected somehow to the main bridge
+ * device. These devices are usually audio/video muxers/encoders/decoders or
+ * sensors and webcam controllers.
+ *
+ * Usually these devices are controlled through an i2c bus, but other busses
+ * may also be used.
+ *
+ * The v4l2_subdev struct provides a way of accessing these devices in a
+ * generic manner. Most operations that these sub-devices support fall in
+ * a few categories: core ops, audio ops, video ops and tuner ops.
+ *
+ * More categories can be added if needed, although this should remain a
+ * limited set (no more than approx. 8 categories).
+ *
+ * Each category has its own set of ops that subdev drivers can implement.
+ *
+ * A subdev driver can leave the pointer to the category ops NULL if
+ * it does not implement them (e.g. an audio subdev will generally not
+ * implement the video category ops). The exception is the core category:
+ * this must always be present.
+ *
+ * These ops are all used internally so it is no problem to change, remove
+ * or add ops or move ops from one to another category. Currently these
+ * ops are based on the original ioctls, but since ops are not limited to
+ * one argument there is room for improvement here once all i2c subdev
+ * drivers are converted to use these ops.
  */
 
-/* Core ops: it is highly recommended to implement at least these ops:
-
-   log_status
-   g_register
-   s_register
-
-   This provides basic debugging support.
-
-   The ioctl ops is meant for generic ioctl-like commands. Depending on
-   the use-case it might be better to use subdev-specific ops (currently
-   not yet implemented) since ops provide proper type-checking.
+/*
+ * Core ops: it is highly recommended to implement at least these ops:
+ *
+ * log_status
+ * g_register
+ * s_register
+ *
+ * This provides basic debugging support.
+ *
+ * The ioctl ops is meant for generic ioctl-like commands. Depending on
+ * the use-case it might be better to use subdev-specific ops (currently
+ * not yet implemented) since ops provide proper type-checking.
  */
 
 /* Subdevice external IO pin configuration */
@@ -110,18 +115,32 @@ struct v4l2_decode_vbi_line {
 #define V4L2_SUBDEV_IO_PIN_SET_VALUE	(1 << 3) /* Set output value */
 #define V4L2_SUBDEV_IO_PIN_ACTIVE_LOW	(1 << 4) /* ACTIVE HIGH assumed */
 
+/**
+ * struct v4l2_subdev_io_pin_config - Subdevice external IO pin configuration
+ *
+ * @flags: bitmask with flags for this pin's config:
+ *	   %V4L2_SUBDEV_IO_PIN_DISABLE - disables a pin config,
+ *	   %V4L2_SUBDEV_IO_PIN_OUTPUT - if pin is an output,
+ *	   %V4L2_SUBDEV_IO_PIN_INPUT - if pin is an input,
+ *	   %V4L2_SUBDEV_IO_PIN_SET_VALUE - to set the output value via @value
+ *	   and %V4L2_SUBDEV_IO_PIN_ACTIVE_LOW - if active is 0.
+ * @pin: Chip external IO pin to configure
+ * @function: Internal signal pad/function to route to IO pin
+ * @value: Initial value for pin - e.g. GPIO output value
+ * @strength: Pin drive strength
+ */
 struct v4l2_subdev_io_pin_config {
-	u32 flags;	/* V4L2_SUBDEV_IO_PIN_* flags for this pin's config */
-	u8 pin;		/* Chip external IO pin to configure */
-	u8 function;	/* Internal signal pad/function to route to IO pin */
-	u8 value;	/* Initial value for pin - e.g. GPIO output value */
-	u8 strength;	/* Pin drive strength */
+	u32 flags;
+	u8 pin;
+	u8 function;
+	u8 value;
+	u8 strength;
 };
 
 /**
  * struct v4l2_subdev_core_ops - Define core ops callbacks for subdevs
  *
- * @log_status: callback for VIDIOC_LOG_STATUS ioctl handler code.
+ * @log_status: callback for %VIDIOC_LOG_STATUS ioctl handler code.
  *
  * @s_io_pin_config: configure one or more chip I/O pins for chips that
  *	multiplex different internal signal pads out to IO pins.  This function
@@ -149,9 +168,9 @@ struct v4l2_subdev_io_pin_config {
  * @compat_ioctl32: called when a 32 bits application uses a 64 bits Kernel,
  *		    in order to fix data passed from/to userspace.
  *
- * @g_register: callback for VIDIOC_G_REGISTER ioctl handler code.
+ * @g_register: callback for %VIDIOC_G_REGISTER ioctl handler code.
  *
- * @s_register: callback for VIDIOC_G_REGISTER ioctl handler code.
+ * @s_register: callback for %VIDIOC_G_REGISTER ioctl handler code.
  *
  * @s_power: puts subdevice in power saving mode (on == 0) or normal operation
  *	mode (on == 1).
@@ -159,7 +178,7 @@ struct v4l2_subdev_io_pin_config {
  * @interrupt_service_routine: Called by the bridge chip's interrupt service
  *	handler, when an interrupt status has be raised due to this subdev,
  *	so that this subdev can handle the details.  It may schedule work to be
- *	performed later.  It must not sleep.  *Called from an IRQ context*.
+ *	performed later.  It must not sleep. **Called from an IRQ context**.
  *
  * @subscribe_event: used by the drivers to request the control framework that
  *		     for it to be warned when the value of a control changes.
@@ -198,25 +217,25 @@ struct v4l2_subdev_core_ops {
 /**
  * struct s_radio - Callbacks used when v4l device was opened in radio mode.
  *
- * @s_radio: callback for VIDIOC_S_RADIO ioctl handler code.
+ * @s_radio: callback for %VIDIOC_S_RADIO ioctl handler code.
  *
- * @s_frequency: callback for VIDIOC_S_FREQUENCY ioctl handler code.
+ * @s_frequency: callback for %VIDIOC_S_FREQUENCY ioctl handler code.
  *
- * @g_frequency: callback for VIDIOC_G_FREQUENCY ioctl handler code.
- *		 freq->type must be filled in. Normally done by video_ioctl2
- *		or the bridge driver.
+ * @g_frequency: callback for %VIDIOC_G_FREQUENCY ioctl handler code.
+ *		 freq->type must be filled in. Normally done by video_ioctl2()
+ *		 or the bridge driver.
  *
- * @enum_freq_bands: callback for VIDIOC_ENUM_FREQ_BANDS ioctl handler code.
+ * @enum_freq_bands: callback for %VIDIOC_ENUM_FREQ_BANDS ioctl handler code.
  *
- * @g_tuner: callback for VIDIOC_G_TUNER ioctl handler code.
+ * @g_tuner: callback for %VIDIOC_G_TUNER ioctl handler code.
  *
- * @s_tuner: callback for VIDIOC_S_TUNER ioctl handler code. vt->type must be
+ * @s_tuner: callback for %VIDIOC_S_TUNER ioctl handler code. &vt->type must be
  *	     filled in. Normally done by video_ioctl2 or the
- *	bridge driver.
+ *	     bridge driver.
  *
- * @g_modulator: callback for VIDIOC_G_MODULATOR ioctl handler code.
+ * @g_modulator: callback for %VIDIOC_G_MODULATOR ioctl handler code.
  *
- * @s_modulator: callback for VIDIOC_S_MODULATOR ioctl handler code.
+ * @s_modulator: callback for %VIDIOC_S_MODULATOR ioctl handler code.
  *
  * @s_type_addr: sets tuner type and its I2C addr.
  *
@@ -247,7 +266,7 @@ struct v4l2_subdev_tuner_ops {
  * @s_i2s_clock_freq: sets I2S speed in bps. This is used to provide a standard
  *	way to select I2S clock used by driving digital audio streams at some
  *	board designs. Usual values for the frequency are 1024000 and 2048000.
- *	If the frequency is not supported, then -EINVAL is returned.
+ *	If the frequency is not supported, then %-EINVAL is returned.
  *
  * @s_routing: used to define the input and/or output pins of an audio chip,
  *	and any additional configuration data.
@@ -279,7 +298,8 @@ struct v4l2_subdev_audio_ops {
 /**
  * struct v4l2_mbus_frame_desc_entry - media bus frame description structure
  *
- * @flags: V4L2_MBUS_FRAME_DESC_FL_* flags
+ * @flags: bitmask flags: %V4L2_MBUS_FRAME_DESC_FL_LEN_MAX and
+ *			  %V4L2_MBUS_FRAME_DESC_FL_BLOB.
  * @pixelcode: media bus pixel code, valid if FRAME_DESC_FL_BLOB is not set
  * @length: number of octets per frame, valid if V4L2_MBUS_FRAME_DESC_FL_BLOB
  *	    is set
@@ -304,7 +324,7 @@ struct v4l2_mbus_frame_desc {
 
 /**
  * struct v4l2_subdev_video_ops - Callbacks used when v4l device was opened
- * 				  in video mode.
+ *				  in video mode.
  *
  * @s_routing: see s_routing in audio_ops, except this version is for video
  *	devices.
@@ -314,9 +334,9 @@ struct v4l2_mbus_frame_desc {
  *	regarding clock frequency dividers, etc. If not used, then set flags
  *	to 0. If the frequency is not supported, then -EINVAL is returned.
  *
- * @g_std: callback for VIDIOC_G_STD ioctl handler code.
+ * @g_std: callback for %VIDIOC_G_STD ioctl handler code.
  *
- * @s_std: callback for VIDIOC_S_STD ioctl handler code.
+ * @s_std: callback for %VIDIOC_S_STD ioctl handler code.
  *
  * @s_std_output: set v4l2_std_id for video OUTPUT devices. This is ignored by
  *	video input devices.
@@ -324,33 +344,33 @@ struct v4l2_mbus_frame_desc {
  * @g_std_output: get current standard for video OUTPUT devices. This is ignored
  *	by video input devices.
  *
- * @querystd: callback for VIDIOC_QUERYSTD ioctl handler code.
+ * @querystd: callback for %VIDIOC_QUERYSTD ioctl handler code.
  *
- * @g_tvnorms: get v4l2_std_id with all standards supported by the video
+ * @g_tvnorms: get &v4l2_std_id with all standards supported by the video
  *	CAPTURE device. This is ignored by video output devices.
  *
  * @g_tvnorms_output: get v4l2_std_id with all standards supported by the video
  *	OUTPUT device. This is ignored by video capture devices.
  *
- * @g_input_status: get input status. Same as the status field in the v4l2_input
- *	struct.
+ * @g_input_status: get input status. Same as the status field in the
+ *	&struct &v4l2_input
  *
  * @s_stream: used to notify the driver that a video stream will start or has
  *	stopped.
  *
- * @cropcap: callback for VIDIOC_CROPCAP ioctl handler code.
+ * @cropcap: callback for %VIDIOC_CROPCAP ioctl handler code.
  *
- * @g_crop: callback for VIDIOC_G_CROP ioctl handler code.
+ * @g_crop: callback for %VIDIOC_G_CROP ioctl handler code.
  *
- * @s_crop: callback for VIDIOC_S_CROP ioctl handler code.
+ * @s_crop: callback for %VIDIOC_S_CROP ioctl handler code.
  *
- * @g_parm: callback for VIDIOC_G_PARM ioctl handler code.
+ * @g_parm: callback for %VIDIOC_G_PARM ioctl handler code.
  *
- * @s_parm: callback for VIDIOC_S_PARM ioctl handler code.
+ * @s_parm: callback for %VIDIOC_S_PARM ioctl handler code.
  *
- * @g_frame_interval: callback for VIDIOC_G_FRAMEINTERVAL ioctl handler code.
+ * @g_frame_interval: callback for %VIDIOC_G_FRAMEINTERVAL ioctl handler code.
  *
- * @s_frame_interval: callback for VIDIOC_S_FRAMEINTERVAL ioctl handler code.
+ * @s_frame_interval: callback for %VIDIOC_S_FRAMEINTERVAL ioctl handler code.
  *
  * @s_dv_timings: Set custom dv timings in the sub device. This is used
  *	when sub device is capable of setting detailed timing information
@@ -358,7 +378,7 @@ struct v4l2_mbus_frame_desc {
  *
  * @g_dv_timings: Get custom dv timings in the sub device.
  *
- * @query_dv_timings: callback for VIDIOC_QUERY_DV_TIMINGS ioctl handler code.
+ * @query_dv_timings: callback for %VIDIOC_QUERY_DV_TIMINGS ioctl handler code.
  *
  * @g_mbus_config: get supported mediabus configurations
  *
@@ -407,31 +427,31 @@ struct v4l2_subdev_video_ops {
 
 /**
  * struct v4l2_subdev_vbi_ops - Callbacks used when v4l device was opened
- * 				  in video mode via the vbi device node.
+ *				  in video mode via the vbi device node.
  *
  *  @decode_vbi_line: video decoders that support sliced VBI need to implement
- *	this ioctl. Field p of the v4l2_sliced_vbi_line struct is set to the
+ *	this ioctl. Field p of the &struct v4l2_sliced_vbi_line is set to the
  *	start of the VBI data that was generated by the decoder. The driver
  *	then parses the sliced VBI data and sets the other fields in the
  *	struct accordingly. The pointer p is updated to point to the start of
  *	the payload which can be copied verbatim into the data field of the
- *	v4l2_sliced_vbi_data struct. If no valid VBI data was found, then the
+ *	&struct v4l2_sliced_vbi_data. If no valid VBI data was found, then the
  *	type field is set to 0 on return.
  *
  * @s_vbi_data: used to generate VBI signals on a video signal.
- *	v4l2_sliced_vbi_data is filled with the data packets that should be
- *	output. Note that if you set the line field to 0, then that VBI signal
- *	is disabled. If no valid VBI data was found, then the type field is
- *	set to 0 on return.
+ *	&struct v4l2_sliced_vbi_data is filled with the data packets that
+ *	should be output. Note that if you set the line field to 0, then that
+ *	VBI signal is disabled. If no valid VBI data was found, then the type
+ *	field is set to 0 on return.
  *
  * @g_vbi_data: used to obtain the sliced VBI packet from a readback register.
  *	Not all video decoders support this. If no data is available because
- *	the readback register contains invalid or erroneous data -EIO is
+ *	the readback register contains invalid or erroneous data %-EIO is
  *	returned. Note that you must fill in the 'id' member and the 'field'
  *	member (to determine whether CC data from the first or second field
  *	should be obtained).
  *
- * @g_sliced_vbi_cap: callback for VIDIOC_SLICED_VBI_CAP ioctl handler code.
+ * @g_sliced_vbi_cap: callback for %VIDIOC_SLICED_VBI_CAP ioctl handler code.
  *
  * @s_raw_fmt: setup the video encoder/decoder for raw VBI.
  *
@@ -464,58 +484,99 @@ struct v4l2_subdev_sensor_ops {
 	int (*g_skip_frames)(struct v4l2_subdev *sd, u32 *frames);
 };
 
-/*
-   [rt]x_g_parameters: Get the current operating parameters and state of the
-	the IR receiver or transmitter.
-
-   [rt]x_s_parameters: Set the current operating parameters and state of the
-	the IR receiver or transmitter.  It is recommended to call
-	[rt]x_g_parameters first to fill out the current state, and only change
-	the fields that need to be changed.  Upon return, the actual device
-	operating parameters and state will be returned.  Note that hardware
-	limitations may prevent the actual settings from matching the requested
-	settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
-	was requested.  An exception is when the shutdown parameter is true.
-	The last used operational parameters will be returned, but the actual
-	state of the hardware be different to minimize power consumption and
-	processing when shutdown is true.
-
-   rx_read: Reads received codes or pulse width data.
-	The semantics are similar to a non-blocking read() call.
-
-   tx_write: Writes codes or pulse width data for transmission.
-	The semantics are similar to a non-blocking write() call.
+/**
+ * enum v4l2_subdev_ir_mode- describes the type of IR supported
+ *
+ * @V4L2_SUBDEV_IR_MODE_PULSE_WIDTH: IR uses struct ir_raw_event records
  */
-
 enum v4l2_subdev_ir_mode {
-	V4L2_SUBDEV_IR_MODE_PULSE_WIDTH, /* uses struct ir_raw_event records */
+	V4L2_SUBDEV_IR_MODE_PULSE_WIDTH,
 };
 
+/**
+ * struct v4l2_subdev_ir_parameters - Parameters for IR TX or TX
+ *
+ * @bytes_per_data_element: bytes per data element of data in read or
+ *	write call.
+ * @mode: IR mode as defined by &enum v4l2_subdev_ir_mode.
+ * @enable: device is active if true
+ * @interrupt_enable: IR interrupts are enabled if true
+ * @shutdown: if true: set hardware to low/no power, false: normal mode
+ *
+ * @modulation: if true, it uses carrier, if false: baseband
+ * @max_pulse_width:  maximum pulse width in ns, valid only for baseband signal
+ * @carrier_freq: carrier frequency in Hz, valid only for modulated signal
+ * @duty_cycle: duty cycle percentage, valid only for modulated signal
+ * @invert_level: invert signal level
+ *
+ * @invert_carrier_sense: Send 0/space as a carrier burst. used only in TX.
+ *
+ * @noise_filter_min_width: min time of a valid pulse, in ns. Used only for RX.
+ * @carrier_range_lower: Lower carrier range, in Hz, valid only for modulated
+ *	signal. Used only for RX.
+ * @carrier_range_upper: Upper carrier range, in Hz, valid only for modulated
+ *	signal. Used only for RX.
+ * @resolution: The receive resolution, in ns . Used only for RX.
+ */
 struct v4l2_subdev_ir_parameters {
-	/* Either Rx or Tx */
-	unsigned int bytes_per_data_element; /* of data in read or write call */
+	unsigned int bytes_per_data_element;
 	enum v4l2_subdev_ir_mode mode;
 
 	bool enable;
 	bool interrupt_enable;
-	bool shutdown; /* true: set hardware to low/no power, false: normal */
+	bool shutdown;
 
-	bool modulation;           /* true: uses carrier, false: baseband */
-	u32 max_pulse_width;       /* ns,      valid only for baseband signal */
-	unsigned int carrier_freq; /* Hz,      valid only for modulated signal*/
-	unsigned int duty_cycle;   /* percent, valid only for modulated signal*/
-	bool invert_level;	   /* invert signal level */
+	bool modulation;
+	u32 max_pulse_width;
+	unsigned int carrier_freq;
+	unsigned int duty_cycle;
+	bool invert_level;
 
 	/* Tx only */
-	bool invert_carrier_sense; /* Send 0/space as a carrier burst */
+	bool invert_carrier_sense;
 
 	/* Rx only */
-	u32 noise_filter_min_width;       /* ns, min time of a valid pulse */
-	unsigned int carrier_range_lower; /* Hz, valid only for modulated sig */
-	unsigned int carrier_range_upper; /* Hz, valid only for modulated sig */
-	u32 resolution;                   /* ns */
+	u32 noise_filter_min_width;
+	unsigned int carrier_range_lower;
+	unsigned int carrier_range_upper;
+	u32 resolution;
 };
 
+/**
+ * struct v4l2_subdev_ir_ops - operations for IR subdevices
+ *
+ * @rx_read: Reads received codes or pulse width data.
+ *	The semantics are similar to a non-blocking read() call.
+ * @rx_g_parameters: Get the current operating parameters and state of the
+ *	the IR receiver.
+ * @rx_s_parameters: Set the current operating parameters and state of the
+ *	the IR receiver.  It is recommended to call
+ *	[rt]x_g_parameters first to fill out the current state, and only change
+ *	the fields that need to be changed.  Upon return, the actual device
+ *	operating parameters and state will be returned.  Note that hardware
+ *	limitations may prevent the actual settings from matching the requested
+ *	settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
+ *	was requested.  An exception is when the shutdown parameter is true.
+ *	The last used operational parameters will be returned, but the actual
+ *	state of the hardware be different to minimize power consumption and
+ *	processing when shutdown is true.
+ *
+ * @tx_write: Writes codes or pulse width data for transmission.
+ *	The semantics are similar to a non-blocking write() call.
+ * @tx_g_parameters: Get the current operating parameters and state of the
+ *	the IR transmitter.
+ * @tx_s_parameters: Set the current operating parameters and state of the
+ *	the IR transmitter.  It is recommended to call
+ *	[rt]x_g_parameters first to fill out the current state, and only change
+ *	the fields that need to be changed.  Upon return, the actual device
+ *	operating parameters and state will be returned.  Note that hardware
+ *	limitations may prevent the actual settings from matching the requested
+ *	settings - e.g. an actual carrier setting of 35,904 Hz when 36,000 Hz
+ *	was requested.  An exception is when the shutdown parameter is true.
+ *	The last used operational parameters will be returned, but the actual
+ *	state of the hardware be different to minimize power consumption and
+ *	processing when shutdown is true.
+ */
 struct v4l2_subdev_ir_ops {
 	/* Receiver */
 	int (*rx_read)(struct v4l2_subdev *sd, u8 *buf, size_t count,
@@ -536,11 +597,16 @@ struct v4l2_subdev_ir_ops {
 				struct v4l2_subdev_ir_parameters *params);
 };
 
-/*
- * Used for storing subdev pad information. This structure only needs
- * to be passed to the pad op if the 'which' field of the main argument
- * is set to V4L2_SUBDEV_FORMAT_TRY. For V4L2_SUBDEV_FORMAT_ACTIVE it is
- * safe to pass NULL.
+/**
+ * struct v4l2_subdev_pad_config - Used for storing subdev pad information.
+ *
+ * @try_fmt: pointer to &struct v4l2_mbus_framefmt
+ * @try_crop: pointer to &struct v4l2_rect to be used for crop
+ * @try_compose: pointer to &struct v4l2_rect to be used for compose
+ *
+ * This structure only needs to be passed to the pad op if the 'which' field
+ * of the main argument is set to %V4L2_SUBDEV_FORMAT_TRY. For
+ * %V4L2_SUBDEV_FORMAT_ACTIVE it is safe to pass %NULL.
  */
 struct v4l2_subdev_pad_config {
 	struct v4l2_mbus_framefmt try_fmt;
@@ -552,30 +618,30 @@ struct v4l2_subdev_pad_config {
  * struct v4l2_subdev_pad_ops - v4l2-subdev pad level operations
  *
  * @init_cfg: initialize the pad config to default values
- * @enum_mbus_code: callback for VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl handler
+ * @enum_mbus_code: callback for %VIDIOC_SUBDEV_ENUM_MBUS_CODE ioctl handler
  *		    code.
- * @enum_frame_size: callback for VIDIOC_SUBDEV_ENUM_FRAME_SIZE ioctl handler
+ * @enum_frame_size: callback for %VIDIOC_SUBDEV_ENUM_FRAME_SIZE ioctl handler
  *		     code.
  *
- * @enum_frame_interval: callback for VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL ioctl
+ * @enum_frame_interval: callback for %VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL ioctl
  *			 handler code.
  *
- * @get_fmt: callback for VIDIOC_SUBDEV_G_FMT ioctl handler code.
+ * @get_fmt: callback for %VIDIOC_SUBDEV_G_FMT ioctl handler code.
  *
- * @set_fmt: callback for VIDIOC_SUBDEV_S_FMT ioctl handler code.
+ * @set_fmt: callback for %VIDIOC_SUBDEV_S_FMT ioctl handler code.
  *
- * @get_selection: callback for VIDIOC_SUBDEV_G_SELECTION ioctl handler code.
+ * @get_selection: callback for %VIDIOC_SUBDEV_G_SELECTION ioctl handler code.
  *
- * @set_selection: callback for VIDIOC_SUBDEV_S_SELECTION ioctl handler code.
+ * @set_selection: callback for %VIDIOC_SUBDEV_S_SELECTION ioctl handler code.
  *
- * @get_edid: callback for VIDIOC_SUBDEV_G_EDID ioctl handler code.
+ * @get_edid: callback for %VIDIOC_SUBDEV_G_EDID ioctl handler code.
  *
- * @set_edid: callback for VIDIOC_SUBDEV_S_EDID ioctl handler code.
+ * @set_edid: callback for %VIDIOC_SUBDEV_S_EDID ioctl handler code.
  *
- * @dv_timings_cap: callback for VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl handler
+ * @dv_timings_cap: callback for %VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl handler
  *		    code.
  *
- * @enum_dv_timings: callback for VIDIOC_SUBDEV_ENUM_DV_TIMINGS ioctl handler
+ * @enum_dv_timings: callback for %VIDIOC_SUBDEV_ENUM_DV_TIMINGS ioctl handler
  *		     code.
  *
  * @link_validate: used by the media controller code to check if the links
@@ -627,6 +693,18 @@ struct v4l2_subdev_pad_ops {
 			      struct v4l2_mbus_frame_desc *fd);
 };
 
+/**
+ * struct v4l2_subdev_ops - Subdev operations
+ *
+ * @core: pointer to &struct v4l2_subdev_core_ops. Can be %NULL
+ * @tuner: pointer to &struct v4l2_subdev_tuner_ops. Can be %NULL
+ * @audio: pointer to &struct v4l2_subdev_audio_ops. Can be %NULL
+ * @video: pointer to &struct v4l2_subdev_video_ops. Can be %NULL
+ * @vbi: pointer to &struct v4l2_subdev_vbi_ops. Can be %NULL
+ * @ir: pointer to &struct v4l2_subdev_ir_ops. Can be %NULL
+ * @sensor: pointer to &struct v4l2_subdev_sensor_ops. Can be %NULL
+ * @pad: pointer to &struct v4l2_subdev_pad_ops. Can be %NULL
+ */
 struct v4l2_subdev_ops {
 	const struct v4l2_subdev_core_ops	*core;
 	const struct v4l2_subdev_tuner_ops	*tuner;
@@ -638,19 +716,22 @@ struct v4l2_subdev_ops {
 	const struct v4l2_subdev_pad_ops	*pad;
 };
 
-/*
- * Internal ops. Never call this from drivers, only the v4l2 framework can call
- * these ops.
+/**
+ * struct v4l2_subdev_internal_ops - V4L2 subdev internal ops
  *
- * registered: called when this subdev is registered. When called the v4l2_dev
+ * @registered: called when this subdev is registered. When called the v4l2_dev
  *	field is set to the correct v4l2_device.
  *
- * unregistered: called when this subdev is unregistered. When called the
+ * @unregistered: called when this subdev is unregistered. When called the
  *	v4l2_dev field is still set to the correct v4l2_device.
  *
- * open: called when the subdev device node is opened by an application.
+ * @open: called when the subdev device node is opened by an application.
  *
- * close: called when the subdev device node is closed.
+ * @close: called when the subdev device node is closed.
+ *
+ * .. note::
+ *	Never call this from drivers, only the v4l2 framework can call
+ *	these ops.
  */
 struct v4l2_subdev_internal_ops {
 	int (*registered)(struct v4l2_subdev *sd);
@@ -672,17 +753,60 @@ struct v4l2_subdev_internal_ops {
 
 struct regulator_bulk_data;
 
+/**
+ * struct v4l2_subdev_platform_data - regulators config struct
+ *
+ * @regulators: Optional regulators used to power on/off the subdevice
+ * @num_regulators: Number of regululators
+ * @host_priv: Per-subdevice data, specific for a certain video host device
+ */
 struct v4l2_subdev_platform_data {
-	/* Optional regulators uset to power on/off the subdevice */
 	struct regulator_bulk_data *regulators;
 	int num_regulators;
 
-	/* Per-subdevice data, specific for a certain video host device */
 	void *host_priv;
 };
 
-/* Each instance of a subdev driver should create this struct, either
-   stand-alone or embedded in a larger struct.
+/**
+ * struct v4l2_subdev - describes a V4L2 sub-device
+ *
+ * @entity: pointer to &struct media_entity
+ * @list: List of sub-devices
+ * @owner: The owner is the same as the driver's &struct device owner.
+ * @owner_v4l2_dev: true if the &sd->owner matches the owner of &v4l2_dev->dev
+ *	ownner. Initialized by v4l2_device_register_subdev().
+ * @flags: subdev flags. Can be:
+ *   %V4L2_SUBDEV_FL_IS_I2C - Set this flag if this subdev is a i2c device;
+ *   %V4L2_SUBDEV_FL_IS_SPI - Set this flag if this subdev is a spi device;
+ *   %V4L2_SUBDEV_FL_HAS_DEVNODE - Set this flag if this subdev needs a
+ *   device node;
+ *   %V4L2_SUBDEV_FL_HAS_EVENTS -  Set this flag if this subdev generates
+ *   events.
+ *
+ * @v4l2_dev: pointer to &struct v4l2_device
+ * @ops: pointer to &struct v4l2_subdev_ops
+ * @internal_ops: pointer to &struct v4l2_subdev_internal_ops.
+ *	Never call these internal ops from within a driver!
+ * @ctrl_handler: The control handler of this subdev. May be NULL.
+ * @name: Name of the sub-device. Please notice that the name must be unique.
+ * @grp_id: can be used to group similar subdevs. Value is driver-specific
+ * @dev_priv: pointer to private data
+ * @host_priv: pointer to private data used by the device where the subdev
+ *	is attached.
+ * @devnode: subdev device node
+ * @dev: pointer to the physical device, if any
+ * @of_node: The device_node of the subdev, usually the same as dev->of_node.
+ * @async_list: Links this subdev to a global subdev_list or @notifier->done
+ *	list.
+ * @asd: Pointer to respective &struct v4l2_async_subdev.
+ * @notifier: Pointer to the managing notifier.
+ * @pdata: common part of subdevice platform data
+ *
+ * Each instance of a subdev driver should create this struct, either
+ * stand-alone or embedded in a larger struct.
+ *
+ * This structure should be initialized by v4l2_subdev_init() or one of
+ * its variants: v4l2_spi_subdev_init(), v4l2_i2c_subdev_init().
  */
 struct v4l2_subdev {
 #if defined(CONFIG_MEDIA_CONTROLLER)
@@ -694,30 +818,18 @@ struct v4l2_subdev {
 	u32 flags;
 	struct v4l2_device *v4l2_dev;
 	const struct v4l2_subdev_ops *ops;
-	/* Never call these internal ops from within a driver! */
 	const struct v4l2_subdev_internal_ops *internal_ops;
-	/* The control handler of this subdev. May be NULL. */
 	struct v4l2_ctrl_handler *ctrl_handler;
-	/* name must be unique */
 	char name[V4L2_SUBDEV_NAME_SIZE];
-	/* can be used to group similar subdevs, value is driver-specific */
 	u32 grp_id;
-	/* pointer to private data */
 	void *dev_priv;
 	void *host_priv;
-	/* subdev device node */
 	struct video_device *devnode;
-	/* pointer to the physical device, if any */
 	struct device *dev;
-	/* The device_node of the subdev, usually the same as dev->of_node. */
 	struct device_node *of_node;
-	/* Links this subdev to a global subdev_list or @notifier->done list. */
 	struct list_head async_list;
-	/* Pointer to respective struct v4l2_async_subdev. */
 	struct v4l2_async_subdev *asd;
-	/* Pointer to the managing notifier. */
 	struct v4l2_async_notifier *notifier;
-	/* common part of subdevice platform data */
 	struct v4l2_subdev_platform_data *pdata;
 };
 
@@ -726,8 +838,11 @@ struct v4l2_subdev {
 #define vdev_to_v4l2_subdev(vdev) \
 	((struct v4l2_subdev *)video_get_drvdata(vdev))
 
-/*
- * Used for storing subdev information per file handle
+/**
+ * struct v4l2_subdev_fh - Used for storing subdev information per file handle
+ *
+ * @vfh: pointer to struct v4l2_fh
+ * @pad: pointer to v4l2_subdev_pad_config
  */
 struct v4l2_subdev_fh {
 	struct v4l2_fh vfh;
@@ -757,53 +872,132 @@ __V4L2_SUBDEV_MK_GET_TRY(v4l2_rect, v4l2_subdev_get_try_compose, try_compose)
 
 extern const struct v4l2_file_operations v4l2_subdev_fops;
 
+/**
+ * v4l2_set_subdevdata - Sets V4L2 dev private device data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @p: pointer to the private device data to be stored.
+ */
 static inline void v4l2_set_subdevdata(struct v4l2_subdev *sd, void *p)
 {
 	sd->dev_priv = p;
 }
 
+/**
+ * v4l2_get_subdevdata - Gets V4L2 dev private device data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ *
+ * Returns the pointer to the private device data to be stored.
+ */
 static inline void *v4l2_get_subdevdata(const struct v4l2_subdev *sd)
 {
 	return sd->dev_priv;
 }
 
+/**
+ * v4l2_set_subdevdata - Sets V4L2 dev private host data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @p: pointer to the private data to be stored.
+ */
 static inline void v4l2_set_subdev_hostdata(struct v4l2_subdev *sd, void *p)
 {
 	sd->host_priv = p;
 }
 
+/**
+ * v4l2_get_subdevdata - Gets V4L2 dev private data
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ *
+ * Returns the pointer to the private host data to be stored.
+ */
 static inline void *v4l2_get_subdev_hostdata(const struct v4l2_subdev *sd)
 {
 	return sd->host_priv;
 }
 
 #ifdef CONFIG_MEDIA_CONTROLLER
+
+/**
+ * v4l2_subdev_link_validate_default - validates a media link
+ *
+ * @sd: pointer to &struct v4l2_subdev
+ * @link: pointer to &struct media_link
+ * @source_fmt: pointer to &struct v4l2_subdev_format
+ * @sink_fmt: pointer to &struct v4l2_subdev_format
+ *
+ * This function ensures that width, height and the media bus pixel
+ * code are equal on both source and sink of the link.
+ */
 int v4l2_subdev_link_validate_default(struct v4l2_subdev *sd,
 				      struct media_link *link,
 				      struct v4l2_subdev_format *source_fmt,
 				      struct v4l2_subdev_format *sink_fmt);
+
+/**
+ * v4l2_subdev_link_validate - validates a media link
+ *
+ * @link: pointer to &struct media_link
+ *
+ * This function calls the subdev's link_validate ops to validate
+ * if a media link is valid for streaming. It also internally
+ * calls v4l2_subdev_link_validate_default() to ensure that
+ * width, height and the media bus pixel code are equal on both
+ * source and sink of the link.
+ */
 int v4l2_subdev_link_validate(struct media_link *link);
 
-struct v4l2_subdev_pad_config *
-v4l2_subdev_alloc_pad_config(struct v4l2_subdev *sd);
+/**
+ * v4l2_subdev_alloc_pad_config - Allocates memory for pad config
+ *
+ * @sd: pointer to struct v4l2_subdev
+ */
+struct
+v4l2_subdev_pad_config *v4l2_subdev_alloc_pad_config(struct v4l2_subdev *sd);
+
+/**
+ * v4l2_subdev_free_pad_config - Frees memory allocated by
+ *	v4l2_subdev_alloc_pad_config().
+ *
+ * @cfg: pointer to &struct v4l2_subdev_pad_config
+ */
 void v4l2_subdev_free_pad_config(struct v4l2_subdev_pad_config *cfg);
 #endif /* CONFIG_MEDIA_CONTROLLER */
 
+/**
+ * v4l2_subdev_init - initializes the sub-device struct
+ *
+ * @sd: pointer to the &struct v4l2_subdev to be initialized
+ * @ops: pointer to &struct v4l2_subdev_ops.
+ */
 void v4l2_subdev_init(struct v4l2_subdev *sd,
 		      const struct v4l2_subdev_ops *ops);
 
-/* Call an ops of a v4l2_subdev, doing the right checks against
-   NULL pointers.
-
-   Example: err = v4l2_subdev_call(sd, video, s_std, norm);
+/*
+ * Call an ops of a v4l2_subdev, doing the right checks against
+ * NULL pointers.
+ *
+ * Example: err = v4l2_subdev_call(sd, video, s_std, norm);
  */
 #define v4l2_subdev_call(sd, o, f, args...)				\
 	(!(sd) ? -ENODEV : (((sd)->ops->o && (sd)->ops->o->f) ?	\
-		(sd)->ops->o->f((sd) , ##args) : -ENOIOCTLCMD))
+		(sd)->ops->o->f((sd), ##args) : -ENOIOCTLCMD))
 
 #define v4l2_subdev_has_op(sd, o, f) \
 	((sd)->ops->o && (sd)->ops->o->f)
 
+/**
+ * v4l2_subdev_notify_event() - Delivers event notification for subdevice
+ * @sd: The subdev for which to deliver the event
+ * @ev: The event to deliver
+ *
+ * Will deliver the specified event to all userspace event listeners which are
+ * subscribed to the v42l subdev event queue as well as to the bridge driver
+ * using the notify callback. The notification type for the notify callback
+ * will be %V4L2_DEVICE_NOTIFY_EVENT.
+ */
 void v4l2_subdev_notify_event(struct v4l2_subdev *sd,
 			      const struct v4l2_event *ev);
 
diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
index bea81c9e3758..946340ce7701 100644
--- a/include/media/videobuf2-core.h
+++ b/include/media/videobuf2-core.h
@@ -85,11 +85,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)(struct device *dev, const struct dma_attrs *attrs,
@@ -271,26 +277,26 @@ struct vb2_buffer {
 /**
  * struct vb2_ops - driver-specific callbacks
  *
- * @queue_setup:	called from VIDIOC_REQBUFS and VIDIOC_CREATE_BUFS
+ * @queue_setup:	called from %VIDIOC_REQBUFS and %VIDIOC_CREATE_BUFS
  *			handlers before memory allocation. It can be called
  *			twice: if the original number of requested buffers
  *			could not be allocated, then it will be called a
  *			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
- *			set in the sizes[] array and optional per-plane
- *			allocator specific device in the alloc_devs[] array.
- *			When called from VIDIOC_REQBUFS, *num_planes == 0, the
+ *			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 device in the alloc_devs\[\] array.
+ *			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
- *			describes the requested number of planes and sizes[]
+ *			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
@@ -305,11 +311,11 @@ struct vb2_buffer {
  *			initialization failure (return != 0) will prevent
  *			queue setup from completing successfully; optional.
  * @buf_prepare:	called every time the buffer is queued from userspace
- *			and from the VIDIOC_PREPARE_BUF ioctl; drivers may
+ *			and from the %VIDIOC_PREPARE_BUF ioctl; drivers may
  *			perform any initialization required before each
  *			hardware operation in this callback; drivers can
  *			access/modify the buffer here as it is still synced for
- *			the CPU; drivers that support VIDIOC_CREATE_BUFS must
+ *			the CPU; drivers that support %VIDIOC_CREATE_BUFS must
  *			also validate the buffer size; if an error is returned,
  *			the buffer will not be queued in driver; optional.
  * @buf_finish:		called before every dequeue of the buffer back to
@@ -317,23 +323,23 @@ struct vb2_buffer {
  *			can access/modify the buffer contents; drivers may
  *			perform any operations required before userspace
  *			accesses the buffer; optional. The buffer state can be
- *			one of the following: DONE and ERROR occur while
- *			streaming is in progress, and the PREPARED state occurs
+ *			one of the following: %DONE and %ERROR occur while
+ *			streaming is in progress, and the %PREPARED state occurs
  *			when the queue has been canceled and all pending
- *			buffers are being returned to their default DEQUEUED
+ *			buffers are being returned to their default %DEQUEUED
  *			state. Typically you only have to do something if the
- *			state is VB2_BUF_STATE_DONE, since in all other cases
+ *			state is %VB2_BUF_STATE_DONE, since in all other cases
  *			the buffer contents will be ignored anyway.
  * @buf_cleanup:	called once before the buffer is freed; drivers may
  *			perform any additional cleanup; optional.
  * @start_streaming:	called once to enter 'streaming' state; the driver may
- *			receive buffers with @buf_queue callback before
- *			@start_streaming is called; the driver gets the number
- *			of already queued buffers in count parameter; driver
- *			can return an error if hardware fails, in that case all
- *			buffers that have been already given by the @buf_queue
- *			callback are to be returned by the driver by calling
- *			@vb2_buffer_done(VB2_BUF_STATE_QUEUED).
+ *			receive buffers with @buf_queue callback
+ *			before @start_streaming is called; the driver gets the
+ *			number of already queued buffers in count parameter;
+ *			driver can return an error if hardware fails, in that
+ *			case all buffers that have been already given by
+ *			the @buf_queue callback are to be returned by the driver
+ *			by calling @vb2_buffer_done\(%VB2_BUF_STATE_QUEUED\).
  *			If you need a minimum number of buffers before you can
  *			start streaming, then set @min_buffers_needed in the
  *			vb2_queue structure. If that is non-zero then
@@ -341,16 +347,16 @@ struct vb2_buffer {
  *			many buffers have been queued up by userspace.
  * @stop_streaming:	called when 'streaming' state must be disabled; driver
  *			should stop any DMA transactions or wait until they
- *			finish and give back all buffers it got from buf_queue()
- *			callback by calling @vb2_buffer_done() with either
- *			VB2_BUF_STATE_DONE or VB2_BUF_STATE_ERROR; may use
+ *			finish and give back all buffers it got from &buf_queue
+ *			callback by calling @vb2_buffer_done\(\) with either
+ *			%VB2_BUF_STATE_DONE or %VB2_BUF_STATE_ERROR; may use
  *			vb2_wait_for_all_buffers() function
  * @buf_queue:		passes buffer vb to the driver; driver may start
  *			hardware operation on this buffer; driver should give
  *			the buffer back by calling vb2_buffer_done() function;
- *			it is allways called after calling STREAMON ioctl;
+ *			it is allways called after calling %VIDIOC_STREAMON ioctl;
  *			might be called before start_streaming callback if user
- *			pre-queued buffers before calling STREAMON.
+ *			pre-queued buffers before calling %VIDIOC_STREAMON.
  */
 struct vb2_ops {
 	int (*queue_setup)(struct vb2_queue *q,
diff --git a/include/uapi/linux/lirc.h b/include/uapi/linux/lirc.h
index 4b3ab2966b5a..991ab4570b8e 100644
--- a/include/uapi/linux/lirc.h
+++ b/include/uapi/linux/lirc.h
@@ -90,20 +90,11 @@
 
 #define LIRC_GET_SEND_MODE             _IOR('i', 0x00000001, __u32)
 #define LIRC_GET_REC_MODE              _IOR('i', 0x00000002, __u32)
-#define LIRC_GET_SEND_CARRIER          _IOR('i', 0x00000003, __u32)
-#define LIRC_GET_REC_CARRIER           _IOR('i', 0x00000004, __u32)
-#define LIRC_GET_SEND_DUTY_CYCLE       _IOR('i', 0x00000005, __u32)
-#define LIRC_GET_REC_DUTY_CYCLE        _IOR('i', 0x00000006, __u32)
 #define LIRC_GET_REC_RESOLUTION        _IOR('i', 0x00000007, __u32)
 
 #define LIRC_GET_MIN_TIMEOUT           _IOR('i', 0x00000008, __u32)
 #define LIRC_GET_MAX_TIMEOUT           _IOR('i', 0x00000009, __u32)
 
-#define LIRC_GET_MIN_FILTER_PULSE      _IOR('i', 0x0000000a, __u32)
-#define LIRC_GET_MAX_FILTER_PULSE      _IOR('i', 0x0000000b, __u32)
-#define LIRC_GET_MIN_FILTER_SPACE      _IOR('i', 0x0000000c, __u32)
-#define LIRC_GET_MAX_FILTER_SPACE      _IOR('i', 0x0000000d, __u32)
-
 /* code length in bits, currently only for LIRC_MODE_LIRCCODE */
 #define LIRC_GET_LENGTH                _IOR('i', 0x0000000f, __u32)
 
@@ -113,7 +104,6 @@
 #define LIRC_SET_SEND_CARRIER          _IOW('i', 0x00000013, __u32)
 #define LIRC_SET_REC_CARRIER           _IOW('i', 0x00000014, __u32)
 #define LIRC_SET_SEND_DUTY_CYCLE       _IOW('i', 0x00000015, __u32)
-#define LIRC_SET_REC_DUTY_CYCLE        _IOW('i', 0x00000016, __u32)
 #define LIRC_SET_TRANSMITTER_MASK      _IOW('i', 0x00000017, __u32)
 
 /*
@@ -127,42 +117,17 @@
 #define LIRC_SET_REC_TIMEOUT_REPORTS   _IOW('i', 0x00000019, __u32)
 
 /*
- * pulses shorter than this are filtered out by hardware (software
- * emulation in lirc_dev?)
- */
-#define LIRC_SET_REC_FILTER_PULSE      _IOW('i', 0x0000001a, __u32)
-/*
- * spaces shorter than this are filtered out by hardware (software
- * emulation in lirc_dev?)
- */
-#define LIRC_SET_REC_FILTER_SPACE      _IOW('i', 0x0000001b, __u32)
-/*
- * if filter cannot be set independently for pulse/space, this should
- * be used
- */
-#define LIRC_SET_REC_FILTER            _IOW('i', 0x0000001c, __u32)
-
-/*
  * if enabled from the next key press on the driver will send
  * LIRC_MODE2_FREQUENCY packets
  */
 #define LIRC_SET_MEASURE_CARRIER_MODE	_IOW('i', 0x0000001d, __u32)
 
 /*
- * to set a range use
- * LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE with the
- * lower bound first and later
- * LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER with the upper bound
+ * to set a range use LIRC_SET_REC_CARRIER_RANGE with the
+ * lower bound first and later LIRC_SET_REC_CARRIER with the upper bound
  */
-
-#define LIRC_SET_REC_DUTY_CYCLE_RANGE  _IOW('i', 0x0000001e, __u32)
 #define LIRC_SET_REC_CARRIER_RANGE     _IOW('i', 0x0000001f, __u32)
 
-#define LIRC_NOTIFY_DECODE             _IO('i', 0x00000020)
-
-#define LIRC_SETUP_START               _IO('i', 0x00000021)
-#define LIRC_SETUP_END                 _IO('i', 0x00000022)
-
 #define LIRC_SET_WIDEBAND_RECEIVER     _IOW('i', 0x00000023, __u32)
 
 #endif