[media] DocBook: update documented fields at struct dmx_demux
There are a few inconsistencies between the old documentation
that got imported into the header and the current status.
Update them, and use the proper doc-nano nomenclature for
struct artuments "@", instead of foo().
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
diff --git a/drivers/media/dvb-core/demux.h b/drivers/media/dvb-core/demux.h
index 54c3df3..ca56d1c 100644
--- a/drivers/media/dvb-core/demux.h
+++ b/drivers/media/dvb-core/demux.h
@@ -214,10 +214,10 @@
*
* @open: This function reserves the demux for use by the caller and, if
* necessary, initializes the demux. When the demux is no longer needed,
- * the function close() should be called. It should be possible for
+ * the function @close should be called. It should be possible for
* multiple clients to access the demux at the same time. Thus, the
* function implementation should increment the demux usage count when
- * open() is called and decrement it when close() is called.
+ * @open is called and decrement it when @close is called.
* The @demux function parameter contains a pointer to the demux API and
* instance data.
* It returns
@@ -227,15 +227,15 @@
*
* @close: This function reserves the demux for use by the caller and, if
* necessary, initializes the demux. When the demux is no longer needed,
- * the function close() should be called. It should be possible for
+ * the function @close should be called. It should be possible for
* multiple clients to access the demux at the same time. Thus, the
* function implementation should increment the demux usage count when
- * open() is called and decrement it when close() is called.
+ * @open is called and decrement it when @close is called.
* The @demux function parameter contains a pointer to the demux API and
* instance data.
* It returns
* 0 on success;
- * -ENODEV, if demux was not in use
+ * -ENODEV, if demux was not in use (e. g. no users);
* -EINVAL, on bad parameter.
*
* @write: This function provides the demux driver with a memory buffer
@@ -253,7 +253,9 @@
* The @count function parameter contains the length of the TS data.
* It returns
* 0 on success;
- * -ENOSYS, if the command is not implemented;
+ * -ERESTARTSYS, if mutex lock was interrupted;
+ * -EINTR, if a signal handling is pending;
+ * -ENODEV, if demux was removed;
* -EINVAL, on bad parameter.
*
* @allocate_ts_feed: Allocates a new TS feed, which is used to filter the TS
@@ -267,11 +269,11 @@
* function for passing received TS packet.
* It returns
* 0 on success;
+ * -ERESTARTSYS, if mutex lock was interrupted;
* -EBUSY, if no more TS feeds is available;
- * -ENOSYS, if the command is not implemented;
* -EINVAL, on bad parameter.
*
- * @release_ts_feed: Releases the resources allocated with allocate_ts_feed().
+ * @release_ts_feed: Releases the resources allocated with @allocate_ts_feed.
* Any filtering in progress on the TS feed should be stopped before
* calling this function.
* The @demux function parameter contains a pointer to the demux API and
@@ -299,11 +301,10 @@
* It returns
* 0 on success;
* -EBUSY, if no more TS feeds is available;
- * -ENOSYS, if the command is not implemented;
* -EINVAL, on bad parameter.
*
* @release_section_feed: Releases the resources allocated with
- * allocate_section_feed(), including allocated filters. Any filtering in
+ * @allocate_section_feed, including allocated filters. Any filtering in
* progress on the section feed should be stopped before calling this
* function.
* The @demux function parameter contains a pointer to the demux API and
@@ -316,31 +317,27 @@
*
* @add_frontend: Registers a connectivity between a demux and a front-end,
* i.e., indicates that the demux can be connected via a call to
- * connect_frontend() to use the given front-end as a TS source. The
+ * @connect_frontend to use the given front-end as a TS source. The
* client of this function has to allocate dynamic or static memory for
* the frontend structure and initialize its fields before calling this
* function. This function is normally called during the driver
* initialization. The caller must not free the memory of the frontend
- * struct before successfully calling remove_frontend().
+ * struct before successfully calling @remove_frontend.
* The @demux function parameter contains a pointer to the demux API and
* instance data.
* The @frontend function parameter contains a pointer to the front-end
* instance data.
* It returns
* 0 on success;
- * -EEXIST, if a front-end with the same value of the id field
- * already registered;
- * -EINUSE, if the demux is in use;
- * -ENOMEM, if no more front-ends can be added;
* -EINVAL, on bad parameter.
*
* @remove_frontend: Indicates that the given front-end, registered by a call
- * to add_frontend(), can no longer be connected as a TS source by this
+ * to @add_frontend, can no longer be connected as a TS source by this
* demux. The function should be called when a front-end driver or a demux
* driver is removed from the system. If the front-end is in use, the
* function fails with the return value of -EBUSY. After successfully
* calling this function, the caller can free the memory of the frontend
- * struct if it was dynamically allocated before the add_frontend()
+ * struct if it was dynamically allocated before the @add_frontend
* operation.
* The @demux function parameter contains a pointer to the demux API and
* instance data.
@@ -348,18 +345,16 @@
* instance data.
* It returns
* 0 on success;
- * -EBUSY, if the front-end is in use, i.e. a call to
- * connect_frontend() has not been followed by a call to
- * disconnect_frontend();
+ * -ENODEV, if the front-end was not found,
* -EINVAL, on bad parameter.
*
* @get_frontends: Provides the APIs of the front-ends that have been
* registered for this demux. Any of the front-ends obtained with this
- * call can be used as a parameter for connect_frontend(). The include
+ * call can be used as a parameter for @connect_frontend. The include
* file demux.h contains the macro DMX_FE_ENTRY() for converting an
- * element of the generic type struct list_head* to the type
- * dmx_frontend_t*. The caller must not free the memory of any of the
- * elements obtained via this function call.
+ * element of the generic type struct &list_head * to the type
+ * struct &dmx_frontend *. The caller must not free the memory of any of
+ * the elements obtained via this function call.
* The @demux function parameter contains a pointer to the demux API and
* instance data.
* It returns a struct list_head pointer to the list of front-end
@@ -367,21 +362,20 @@
*
* @connect_frontend: Connects the TS output of the front-end to the input of
* the demux. A demux can only be connected to a front-end registered to
- * the demux with the function add_frontend(). It may or may not be
+ * the demux with the function @add_frontend. It may or may not be
* possible to connect multiple demuxes to the same front-end, depending
* on the capabilities of the HW platform. When not used, the front-end
- * should be released by calling disconnect_frontend().
+ * should be released by calling @disconnect_frontend.
* The @demux function parameter contains a pointer to the demux API and
* instance data.
* The @frontend function parameter contains a pointer to the front-end
* instance data.
* It returns
* 0 on success;
- * -EBUSY, if the front-end is in use;
* -EINVAL, on bad parameter.
*
* @disconnect_frontend: Disconnects the demux and a front-end previously
- * connected by a connect_frontend() call.
+ * connected by a @connect_frontend call.
* The @demux function parameter contains a pointer to the demux API and
* instance data.
* It returns