[vlc-devel] [PATCH 17/21] include/demux: update documentation related to source data-members

[Filip Roséen]

The previous documentation for the affected data-members is faulty.

Given that both demux_t::s and demux_t::p_next resides inside a union,
demux_t::s would not be NULL when accessed inside a demux_filter
(though it would of course invoke undefined-behavior if it was not the
last member of the union written to).

This commit changes the documentation so that it reflects the real
world.
---
 include/vlc_demux.h | 24 ++++++++----------------
 1 file changed, 8 insertions(+), 16 deletions(-)

diff --git a/include/vlc_demux.h b/include/vlc_demux.h
index 3f7f139..34829cf 100644
--- a/include/vlc_demux.h
+++ b/include/vlc_demux.h
@@ -53,23 +53,15 @@ struct demux_t
     char        *psz_location;
     char        *psz_file;
 
+    /** An anonymous union related to the source entity associated with the
+     * demux_t. A module should only access the member associated with its
+     * capability; see demux_t::s and demux_t::p_next for more information.
+     */
     union {
-        /**
-         * Input stream
-         *
-         * Depending on the module capability:
-         * - "demux": input byte stream (not NULL)
-         * - "access_demux": a NULL pointer
-         * - "demux_filter": undefined
-         */
-        stream_t *s;
-        /**
-         * Input demuxer
-         *
-         * If the module capability is "demux_filter", this is the upstream
-         * demuxer or demux filter. Otherwise, this is undefined.
-         */
-        demux_t *p_next;
+        stream_t     *s; /**< refers to the source stream associated with
+                              capability "demux" and "access_demux". */
+        demux_t *p_next; /**< refers to the upstream demuxer
+                              for modules with capability "demux_filter */
     };
 
     /* es output */
-- 
2.9.2