avformat/avformat: Improve doxy style

Mostly re-indenting and adding some missing references.

libavformat/avformat.h

@@ -1898,8 +1898,8 @@ const AVOutputFormat *av_muxer_iterate(void **opaque);
 /**
  * Iterate over all registered demuxers.
  *
- * @param opaque a pointer where libavformat will store the iteration state. Must
+ * @param opaque a pointer where libavformat will store the iteration state.
- *               point to NULL to start the iteration.
+ *               Must point to NULL to start the iteration.
  *
  * @return the next registered demuxer or NULL when the iteration is
  *         finished
@@ -1963,6 +1963,7 @@ AVStream *avformat_new_stream(AVFormatContext *s, const AVCodec *c);
  *             family of functions. The ownership of the data is transferred to
  *             st.
  * @param size side information size
+ *
  * @return zero on success, a negative AVERROR code on failure. On failure,
  *         the stream is unchanged and the data remains owned by the caller.
  */
@@ -1975,6 +1976,7 @@ int av_stream_add_side_data(AVStream *st, enum AVPacketSideDataType type,
  * @param stream stream
  * @param type   desired side information type
  * @param size   side information size
+ *
  * @return pointer to fresh allocated data or NULL otherwise
  */
 uint8_t *av_stream_new_side_data(AVStream *stream,
@@ -1986,6 +1988,7 @@ uint8_t *av_stream_new_side_data(AVStream *stream,
  * @param type   desired side information type
  * @param size   If supplied, *size will be set to the size of the side data
  *               or to zero if the desired side data is not present.
+ *
  * @return pointer to data if present or NULL otherwise
  */
 uint8_t *av_stream_get_side_data(const AVStream *stream,
@@ -2003,14 +2006,15 @@ AVProgram *av_new_program(AVFormatContext *s, int id);
  * avformat_free_context() can be used to free the context and
  * everything allocated by the framework within it.
  *
- * @param ctx pointee is set to the created format context, or to NULL in
+ * @param ctx           pointee is set to the created format context,
- * case of failure
+ *                      or to NULL in case of failure
  * @param oformat       format to use for allocating the context, if NULL
  *                      format_name and filename are used instead
  * @param format_name   the name of output format to use for allocating the
  *                      context, if NULL filename is used instead
  * @param filename      the name of the filename to use for allocating the
  *                      context, may be NULL
+ *
  * @return  >= 0 in case of success, a negative AVERROR code in case of
  *          failure
  */
@@ -2073,6 +2077,7 @@ const AVInputFormat *av_probe_input_format3(const AVProbeData *pd,
  * @param logctx         the log context
  * @param offset         the offset within the bytestream to probe from
  * @param max_probe_size the maximum probe buffer size (zero for default)
+ *
  * @return the score in case of success, a negative value corresponding to an
  *         the maximal score is AVPROBE_SCORE_MAX
  *         AVERROR code otherwise
@@ -2092,16 +2097,19 @@ int av_probe_input_buffer(AVIOContext *pb, const AVInputFormat **fmt,
  * Open an input stream and read the header. The codecs are not opened.
  * The stream must be closed with avformat_close_input().
  *
- * @param ps Pointer to user-supplied AVFormatContext (allocated by avformat_alloc_context).
+ * @param ps       Pointer to user-supplied AVFormatContext (allocated by
- *           May be a pointer to NULL, in which case an AVFormatContext is allocated by this
+ *                 avformat_alloc_context). May be a pointer to NULL, in
+ *                 which case an AVFormatContext is allocated by this
  *                 function and written into ps.
- *           Note that a user-supplied AVFormatContext will be freed on failure.
+ *                 Note that a user-supplied AVFormatContext will be freed
+ *                 on failure.
  * @param url      URL of the stream to open.
  * @param fmt      If non-NULL, this parameter forces a specific input format.
  *                 Otherwise the format is autodetected.
- * @param options  A dictionary filled with AVFormatContext and demuxer-private options.
+ * @param options  A dictionary filled with AVFormatContext and demuxer-private
- *                 On return this parameter will be destroyed and replaced with a dict containing
+ *                 options.
- *                 options that were not found. May be NULL.
+ *                 On return this parameter will be destroyed and replaced with
+ *                 a dict containing options that were not found. May be NULL.
  *
  * @return 0 on success, a negative AVERROR on failure.
  *
@@ -2140,6 +2148,7 @@ int avformat_find_stream_info(AVFormatContext *ic, AVDictionary **options);
  * @param last  the last found program, the search will start after this
  *              program, or from the beginning if it is NULL
  * @param s     stream index
+ *
  * @return the next program which belongs to s, NULL if no program is found or
  *         the last program is not among the programs of ic.
  */
@@ -2164,10 +2173,12 @@ void av_program_add_stream_index(AVFormatContext *ac, int progid, unsigned int i
  * @param decoder_ret       if non-NULL, returns the decoder for the
  *                          selected stream
  * @param flags             flags; none are currently defined
+ *
  * @return  the non-negative stream number in case of success,
  *          AVERROR_STREAM_NOT_FOUND if no stream with the requested type
  *          could be found,
  *          AVERROR_DECODER_NOT_FOUND if streams were found but no decoder
+ *
  * @note  If av_find_best_stream returns successfully and decoder_ret is not
  *        NULL, then *decoder_ret is guaranteed to be set to a valid AVCodec.
  */
@@ -2212,12 +2223,13 @@ int av_read_frame(AVFormatContext *s, AVPacket *pkt);
  * 'timestamp' in 'stream_index'.
  *
  * @param s            media file handle
- * @param stream_index If stream_index is (-1), a default
+ * @param stream_index If stream_index is (-1), a default stream is selected,
- * stream is selected, and timestamp is automatically converted
+ *                     and timestamp is automatically converted from
- * from AV_TIME_BASE units to the stream specific time_base.
+ *                     AV_TIME_BASE units to the stream specific time_base.
- * @param timestamp Timestamp in AVStream.time_base units
+ * @param timestamp    Timestamp in AVStream.time_base units or, if no stream
- *        or, if no stream is specified, in AV_TIME_BASE units.
+ *                     is specified, in AV_TIME_BASE units.
  * @param flags        flags which select direction and seeking mode
+ *
  * @return >= 0 on success
  */
 int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp,
@@ -2308,16 +2320,22 @@ void avformat_close_input(AVFormatContext **s);
  * Allocate the stream private data and write the stream header to
  * an output media file.
  *
- * @param s Media file handle, must be allocated with avformat_alloc_context().
+ * @param s        Media file handle, must be allocated with
- *          Its oformat field must be set to the desired output format;
+ *                 avformat_alloc_context().
- *          Its pb field must be set to an already opened AVIOContext.
+ *                 Its \ref AVFormatContext.oformat "oformat" field must be set
- * @param options  An AVDictionary filled with AVFormatContext and muxer-private options.
+ *                 to the desired output format;
- *                 On return this parameter will be destroyed and replaced with a dict containing
+ *                 Its \ref AVFormatContext.pb "pb" field must be set to an
- *                 options that were not found. May be NULL.
+ *                 already opened ::AVIOContext.
- *
+ * @param options  An ::AVDictionary filled with AVFormatContext and
- * @return AVSTREAM_INIT_IN_WRITE_HEADER on success if the codec had not already been fully initialized in avformat_init,
+ *                 muxer-private options.
- *         AVSTREAM_INIT_IN_INIT_OUTPUT  on success if the codec had already been fully initialized in avformat_init,
+ *                 On return this parameter will be destroyed and replaced with
- *         negative AVERROR on failure.
+ *                 a dict containing options that were not found. May be NULL.
+ *
+ * @retval AVSTREAM_INIT_IN_WRITE_HEADER On success, if the codec had not already been
+ *                                       fully initialized in avformat_init_output().
+ * @retval AVSTREAM_INIT_IN_INIT_OUTPUT  On success, if the codec had already been fully
+ *                                       initialized in avformat_init_output().
+ * @retval AVERROR                       A negative AVERROR on failure.
  *
  * @see av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_init_output.
  */
@@ -2326,20 +2344,26 @@ int avformat_write_header(AVFormatContext *s, AVDictionary **options);
 
 /**
  * Allocate the stream private data and initialize the codec, but do not write the header.
- * May optionally be used before avformat_write_header to initialize stream parameters
+ * May optionally be used before avformat_write_header() to initialize stream parameters
  * before actually writing the header.
- * If using this function, do not pass the same options to avformat_write_header.
+ * If using this function, do not pass the same options to avformat_write_header().
- *
+ *
- * @param s Media file handle, must be allocated with avformat_alloc_context().
+ * @param s        Media file handle, must be allocated with
- *          Its oformat field must be set to the desired output format;
+ *                 avformat_alloc_context().
- *          Its pb field must be set to an already opened AVIOContext.
+ *                 Its \ref AVFormatContext.oformat "oformat" field must be set
- * @param options  An AVDictionary filled with AVFormatContext and muxer-private options.
+ *                 to the desired output format;
- *                 On return this parameter will be destroyed and replaced with a dict containing
+ *                 Its \ref AVFormatContext.pb "pb" field must be set to an
- *                 options that were not found. May be NULL.
+ *                 already opened ::AVIOContext.
- *
+ * @param options  An ::AVDictionary filled with AVFormatContext and
- * @return AVSTREAM_INIT_IN_WRITE_HEADER on success if the codec requires avformat_write_header to fully initialize,
+ *                 muxer-private options.
- *         AVSTREAM_INIT_IN_INIT_OUTPUT  on success if the codec has been fully initialized,
+ *                 On return this parameter will be destroyed and replaced with
- *         negative AVERROR on failure.
+ *                 a dict containing options that were not found. May be NULL.
+ *
+ * @retval AVSTREAM_INIT_IN_WRITE_HEADER On success, if the codec requires
+ *                                       avformat_write_header to fully initialize.
+ * @retval AVSTREAM_INIT_IN_INIT_OUTPUT  On success, if the codec has been fully
+ *                                       initialized.
+ * @retval AVERROR                       Anegative AVERROR on failure.
  *
  * @see av_opt_find, av_dict_set, avio_open, av_oformat_next, avformat_write_header.
  */
@@ -2512,8 +2536,10 @@ enum AVCodecID av_guess_codec(const AVOutputFormat *fmt, const char *short_name,
  *                   time_base units
  * @param[out] wall  absolute time when that packet whas output,
  *                   in microsecond
- * @return  0 if OK, AVERROR(ENOSYS) if the format does not support it
+ * @retval  0               Success
- * Note: some formats or devices may not allow to measure dts and wall
+ * @retval  AVERROR(ENOSYS) The format does not support it
+ *
+ * @note Some formats or devices may not allow to measure dts and wall
  *       atomically.
  */
 int av_get_output_timestamp(struct AVFormatContext *s, int stream,