Merge remote-tracking branch 'qatar/master'

* qatar/master:
  tls: Use ERR_get_error() in do_tls_poll
  indeo3: Fix a fencepost error.
  mxfdec: Fix comparison of unsigned expression < 0.
  mpegts: set stream id on just created stream, not an unrelated variable
  ra288: return error if input buffer is too small
  ra288: utilize DSPContext.vector_fmul()
  ra288: use memcpy() to copy decoded samples to output
  mace: only calculate output buffer size once
  Remove redundant filename self-references inside files.
  indeo3data: add missing config.h #include for HAVE_BIGENDIAN
  x86: drop pointless ARCH_X86 #ifdef from files in x86 subdirectory
  avplay: reset rdft when closing stream.
  doc/git-howto: expand format-patch and send-email notes.
  lavf: expand doxy for some AVFormatContext fields.

Merged-by: Michael Niedermayer <michaelni@gmx.at>

1 files changed, 44 insertions, 5 deletions

diff --git a/libavformat/avformat.h b/libavformat/avformat.h
index 1b0229daee..cf0dae9c32 100644
--- a/libavformat/avformat.h
+++ b/libavformat/avformat.h
@@ -765,17 +765,56 @@ typedef struct AVChapter {
  * New fields can be added to the end with minor version bumps.
  * Removal, reordering and changes to existing fields require a major
  * version bump.
- * sizeof(AVFormatContext) must not be used outside libav*.
+ * sizeof(AVFormatContext) must not be used outside libav*, use
+ * avformat_alloc_context() to create an AVFormatContext.
  */
 typedef struct AVFormatContext {
-    const AVClass *av_class; /**< Set by avformat_alloc_context. */
-    /* Can only be iformat or oformat, not both at the same time. */
+    /**
+     * A class for logging and AVOptions. Set by avformat_alloc_context().
+     * Exports (de)muxer private options if they exist.
+     */
+    const AVClass *av_class;
+
+    /**
+     * Can only be iformat or oformat, not both at the same time.
+     *
+     * decoding: set by avformat_open_input().
+     * encoding: set by the user.
+     */
     struct AVInputFormat *iformat;
     struct AVOutputFormat *oformat;
+
+    /**
+     * Format private data. This is an AVOptions-enabled struct
+     * if and only if iformat/oformat.priv_class is not NULL.
+     */
     void *priv_data;
+
+    /*
+     * I/O context.
+     *
+     * decoding: either set by the user before avformat_open_input() (then
+     * the user must close it manually) or set by avformat_open_input().
+     * encoding: set by the user.
+     *
+     * Do NOT set this field if AVFMT_NOFILE flag is set in
+     * iformat/oformat.flags. In such a case, the (de)muxer will handle
+     * I/O in some other way and this field will be NULL.
+     */
     AVIOContext *pb;
+
+    /**
+     * A list of all streams in the file. New streams are created with
+     * avformat_new_stream().
+     *
+     * decoding: streams are created by libavformat in avformat_open_input().
+     * If AVFMTCTX_NOHEADER is set in ctx_flags, then new streams may also
+     * appear in av_read_frame().
+     * encoding: streams are created by the user before avformat_write_header().
+     */
     unsigned int nb_streams;
     AVStream **streams;
+
     char filename[1024]; /**< input or output filename */
     /* stream info */
 #if FF_API_TIMESTAMP
@@ -886,8 +925,8 @@ typedef struct AVFormatContext {
     unsigned int probesize;
 
     /**
-     * Maximum time (in AV_TIME_BASE units) during which the input should
-     * be analyzed in av_find_stream_info().
+     * decoding: maximum time (in AV_TIME_BASE units) during which the input should
+     * be analyzed in avformat_find_stream_info().
      */
     int max_analyze_duration;