[FFmpeg-devel] [PATCH] Documentation fixes and updates

[Stefano Sabatini]

On date Saturday 2011-07-23 18:27:14 +0200, Simon A. Eugster encoded:
> Hi,
> 
> The attached patch fixes some parts of the documentation for doxygen
> and adds a few comments.
> 
> Simon
> 
> PS: Please CC me as I'm not registered on the mailing list.

> >From 2c228b6b0adc52dc77e92cc6fff9fd16b4124db0 Mon Sep 17 00:00:00 2001
> From: "Simon A. Eugster" <simon.eu at gmail.com>
> Date: Tue, 19 Jul 2011 20:37:24 +0200
> Subject: [PATCH] lavf: Source code comments added/more detailled
> 
> ---
>  doc/examples/muxing.c  |    6 +++---
>  libavformat/avformat.h |   32 ++++++++++++++++++--------------
>  2 files changed, 21 insertions(+), 17 deletions(-)
> 
> diff --git a/doc/examples/muxing.c b/doc/examples/muxing.c
> index 9f94a78..121cc9e 100644
> --- a/doc/examples/muxing.c
> +++ b/doc/examples/muxing.c
> @@ -372,14 +372,14 @@ static void write_video_frame(AVFormatContext *oc, AVStream *st)
>  
>      if (oc->oformat->flags & AVFMT_RAWPICTURE) {
>          /* raw video case. The API will change slightly in the near
> -           futur for that */
> +           future for that */
>          AVPacket pkt;
>          av_init_packet(&pkt);
>  
>          pkt.flags |= AV_PKT_FLAG_KEY;
>          pkt.stream_index= st->index;
> -        pkt.data= (uint8_t *)picture;
> -        pkt.size= sizeof(AVPicture);
> +        pkt.data = (uint8_t *)picture;
> +        pkt.size = sizeof(AVPicture);
>  
>          ret = av_interleaved_write_frame(oc, &pkt);
>      } else {

Fixed in two different commits.

> diff --git a/libavformat/avformat.h b/libavformat/avformat.h
> index 7c041f6..2c4b584 100644
> --- a/libavformat/avformat.h
> +++ b/libavformat/avformat.h
> @@ -511,21 +511,23 @@ typedef struct AVStream {
>      int64_t first_dts;
>  
>      /**
> -     * encoding: pts generation when outputting stream
> +     * Encoding: Presentation time stamp generation when outputting stream.
> +     *
> +     * See http://dranger.com/ffmpeg/tutorial05.html for an explanation of PTS.
>       */

Uhm, I don't think it is a good idea to link an outdated tutorial in
the official docs.

>      struct AVFrac pts;
>  
>      /**
>       * This is the fundamental unit of time (in seconds) in terms
>       * of which frame timestamps are represented. For fixed-fps content,
> -     * time base should be 1/framerate and timestamp increments should be 1.
> -     * decoding: set by libavformat
> -     * encoding: set by libavformat in av_write_header

> +     * time base should be <tt>1/framerate</tt> and timestamp increments should be 1.

we tend to avoid the use of XML syntax in doxy, as it decreases
readability when reading plain text.

> +     * - decoding: set by libavformat
> +     * - encoding: set by libavformat in av_write_header

that's ok, also av_write_header -> av_write_header()

>       */
>      AVRational time_base;
>      int pts_wrap_bits; /**< number of bits in pts (used for wrapping control) */
>      /* ffmpeg.c private use */
> -    int stream_copy; /**< If set, just copy stream. */
> +    int stream_copy; /**< If set, just copy the stream. */
>      enum AVDiscard discard; ///< Selects which packets can be discarded at will and do not need to be demuxed.
>  
>  #if FF_API_AVSTREAM_QUALITY
> @@ -681,22 +683,24 @@ typedef struct AVChapter {
>  } AVChapter;
>  
>  /**
> - * Format I/O context.
> + * Format I/O context. Can only be \c iformat or \c oformat, not both at the same time.
> + *
>   * 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*.
> + *
> + * \c sizeof(AVFormatContext) must not be used outside libav*.
>   */
>  typedef struct AVFormatContext {
>      const AVClass *av_class; /**< Set by avformat_alloc_context. */
> -    /* Can only be iformat or oformat, not both at the same time. */
> +    // Either iformat or oformat.
>      struct AVInputFormat *iformat;
>      struct AVOutputFormat *oformat;
>      void *priv_data;
> -    AVIOContext *pb;
> -    unsigned int nb_streams;
> +    AVIOContext *pb; /**< Packet buffer */

packet buffer is not the right expansion of the acronym, I think it
was originally PutByte context, before the API was changed.

> +    unsigned int nb_streams; /**< Number of streams in this format context */

nit: number of streams, not upcased, since not a complete sentence

>      AVStream **streams;
> -    char filename[1024]; /**< input or output filename */
> +    char filename[1024]; /**< Input or output filename */
>      /* stream info */
>  #if FF_API_TIMESTAMP
>      /**
> @@ -1087,7 +1091,7 @@ int av_probe_input_buffer(AVIOContext *pb, AVInputFormat **fmt,
>  /**
>   * Allocate all the structures needed to read an input stream.
>   *        This does not open the needed codecs for decoding the stream[s].

> - * @deprecated use avformat_open_input instead.
> + * @deprecated use avformat_open_input() instead.

While at it, "Use"

>   */
>  attribute_deprecated int av_open_input_stream(AVFormatContext **ic_ptr,
>                           AVIOContext *pb, const char *filename,
> @@ -1105,7 +1109,7 @@ attribute_deprecated int av_open_input_stream(AVFormatContext **ic_ptr,
>   *           (NULL if default).
>   * @return 0 if OK, AVERROR_xxx otherwise
>   *
> - * @deprecated use avformat_open_input instead.
> + * @deprecated use avformat_open_input() instead. 
>   */
>  attribute_deprecated int av_open_input_file(AVFormatContext **ic_ptr, const char *filename,
>                         AVInputFormat *fmt,
> @@ -1507,7 +1511,7 @@ int avformat_write_header(AVFormatContext *s, AVDictionary **options);
>   * @param s media file handle
>   * @return 0 if OK, AVERROR_xxx on error
>   *
> - * @deprecated use avformat_write_header.
> + * @deprecated use avformat_write_header().

>   */
>  attribute_deprecated int av_write_header(AVFormatContext *s);
>  #endif

Please send an updated avformat.h patch.
-- 
FFmpeg = Fascinating and Fierce Mythic Peaceful Elected Geek