diff avformat.h @ 6199:fa244b4fe683 libavformat

Fix grammar errors in documentation

--- a/avformat.h	Wed Jun 30 07:55:05 2010 +0000
+++ b/avformat.h	Wed Jun 30 15:38:06 2010 +0000
@@ -42,12 +42,12 @@
 unsigned avformat_version(void);
 
 /**
- * Returns the libavformat build-time configuration.
+ * Return the libavformat build-time configuration.
  */
 const char *avformat_configuration(void);
 
 /**
- * Returns the libavformat license.
+ * Return the libavformat license.
  */
 const char *avformat_license(void);
 
@@ -130,7 +130,7 @@
 typedef struct AVMetadataConv AVMetadataConv;
 
 /**
- * Gets a metadata element with matching key.
+ * Get a metadata element with matching key.
  * @param prev Set to the previous matching element to find the next.
  *             If set to NULL the first matching element is returned.
  * @param flags Allows case as well as suffix-insensitive comparisons.
@@ -141,7 +141,7 @@
 
 #if LIBAVFORMAT_VERSION_MAJOR == 52
 /**
- * Sets the given tag in m, overwriting an existing tag.
+ * Set the given tag in m, overwriting an existing tag.
  * @param key tag key to add to m (will be av_strduped)
  * @param value tag value to add to m (will be av_strduped)
  * @return >= 0 on success otherwise an error code <0
@@ -151,7 +151,7 @@
 #endif
 
 /**
- * Sets the given tag in m, overwriting an existing tag.
+ * Set the given tag in m, overwriting an existing tag.
  * @param key tag key to add to m (will be av_strduped depending on flags)
  * @param value tag value to add to m (will be av_strduped depending on flags).
  *        Passing a NULL value will cause an existing tag to be deleted.
@@ -160,7 +160,7 @@
 int av_metadata_set2(AVMetadata **pm, const char *key, const char *value, int flags);
 
 /**
- * Converts all the metadata sets from ctx according to the source and
+ * Convert all the metadata sets from ctx according to the source and
  * destination conversion tables. If one of the tables is NULL, then
  * tags are converted to/from ffmpeg generic tag names.
  * @param d_conv destination tags format conversion table
@@ -170,7 +170,7 @@
                                                   const AVMetadataConv *s_conv);
 
 /**
- * Frees all the memory allocated for an AVMetadata struct.
+ * Free all the memory allocated for an AVMetadata struct.
  */
 void av_metadata_free(AVMetadata **m);
 
@@ -179,7 +179,7 @@
 
 
 /**
- * Allocates and reads the payload of a packet and initializes its
+ * Allocate and read the payload of a packet and initialize its
  * fields with default values.
  *
  * @param pkt packet
@@ -349,18 +349,18 @@
     /** General purpose read-only value that the format can use. */
     int value;
 
-    /** Starts/resumes playing - only meaningful if using a network-based format
+    /** Start/resume playing - only meaningful if using a network-based format
        (RTSP). */
     int (*read_play)(struct AVFormatContext *);
 
-    /** Pauses playing - only meaningful if using a network-based format
+    /** Pause playing - only meaningful if using a network-based format
        (RTSP). */
     int (*read_pause)(struct AVFormatContext *);
 
     const struct AVCodecTag * const *codec_tag;
 
     /**
-     * Seeks to timestamp ts.
+     * Seek to timestamp ts.
      * Seeking will be done so that the point from which all active streams
      * can be presented successfully will be closest to ts and within min/max_ts.
      * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL.
@@ -790,8 +790,8 @@
 #endif
 
 /**
- * Returns the output format in the list of registered output formats
- * which best matches the provided parameters, or returns NULL if
+ * Return the output format in the list of registered output formats
+ * which best matches the provided parameters, or return NULL if
  * there is no match.
  *
  * @param short_name if non-NULL checks if short_name matches with the
@@ -806,14 +806,14 @@
                                 const char *mime_type);
 
 /**
- * Guesses the codec ID based upon muxer and filename.
+ * Guess the codec ID based upon muxer and filename.
  */
 enum CodecID av_guess_codec(AVOutputFormat *fmt, const char *short_name,
                             const char *filename, const char *mime_type,
                             enum AVMediaType type);
 
 /**
- * Sends a nice hexadecimal dump of a buffer to the specified file stream.
+ * Send a nice hexadecimal dump of a buffer to the specified file stream.
  *
  * @param f The file stream pointer where the dump should be sent to.
  * @param buf buffer
@@ -824,7 +824,7 @@
 void av_hex_dump(FILE *f, uint8_t *buf, int size);
 
 /**
- * Sends a nice hexadecimal dump of a buffer to the log.
+ * Send a nice hexadecimal dump of a buffer to the log.
  *
  * @param avcl A pointer to an arbitrary struct of which the first field is a
  * pointer to an AVClass struct.
@@ -838,7 +838,7 @@
 void av_hex_dump_log(void *avcl, int level, uint8_t *buf, int size);
 
 /**
- * Sends a nice dump of a packet to the specified file stream.
+ * Send a nice dump of a packet to the specified file stream.
  *
  * @param f The file stream pointer where the dump should be sent to.
  * @param pkt packet to dump
@@ -847,7 +847,7 @@
 void av_pkt_dump(FILE *f, AVPacket *pkt, int dump_payload);
 
 /**
- * Sends a nice dump of a packet to the log.
+ * Send a nice dump of a packet to the log.
  *
  * @param avcl A pointer to an arbitrary struct of which the first field is a
  * pointer to an AVClass struct.
@@ -859,7 +859,7 @@
 void av_pkt_dump_log(void *avcl, int level, AVPacket *pkt, int dump_payload);
 
 /**
- * Initializes libavformat and registers all the muxers, demuxers and
+ * Initialize libavformat and register all the muxers, demuxers and
  * protocols. If you do not call this function, then you can select
  * exactly which formats you want to support.
  *
@@ -870,7 +870,7 @@
 void av_register_all(void);
 
 /**
- * Gets the CodecID for the given codec tag tag.
+ * Get the CodecID for the given codec tag tag.
  * If no codec id is found returns CODEC_ID_NONE.
  *
  * @param tags list of supported codec_id-codec_tag pairs, as stored
@@ -879,7 +879,7 @@
 enum CodecID av_codec_get_id(const struct AVCodecTag * const *tags, unsigned int tag);
 
 /**
- * Gets the codec tag for the given codec id id.
+ * Get the codec tag for the given codec id id.
  * If no codec tag is found returns 0.
  *
  * @param tags list of supported codec_id-codec_tag pairs, as stored
@@ -890,12 +890,12 @@
 /* media file input */
 
 /**
- * Finds AVInputFormat based on the short name of the input format.
+ * Find AVInputFormat based on the short name of the input format.
  */
 AVInputFormat *av_find_input_format(const char *short_name);
 
 /**
- * Guesses the file format.
+ * Guess the file format.
  *
  * @param is_opened Whether the file is already opened; determines whether
  *                  demuxers with or without AVFMT_NOFILE are probed.
@@ -903,7 +903,7 @@
 AVInputFormat *av_probe_input_format(AVProbeData *pd, int is_opened);
 
 /**
- * Guesses the file format.
+ * Guess the file format.
  *
  * @param is_opened Whether the file is already opened; determines whether
  *                  demuxers with or without AVFMT_NOFILE are probed.
@@ -916,7 +916,7 @@
 AVInputFormat *av_probe_input_format2(AVProbeData *pd, int is_opened, int *score_max);
 
 /**
- * Allocates all the structures needed to read an input stream.
+ * Allocate all the structures needed to read an input stream.
  *        This does not open the needed codecs for decoding the stream[s].
  */
 int av_open_input_stream(AVFormatContext **ic_ptr,
@@ -924,7 +924,7 @@
                          AVInputFormat *fmt, AVFormatParameters *ap);
 
 /**
- * Opens a media file as input. The codecs are not opened. Only the file
+ * Open a media file as input. The codecs are not opened. Only the file
  * header (if present) is read.
  *
  * @param ic_ptr The opened media file handle is put here.
@@ -948,14 +948,14 @@
 #endif
 
 /**
- * Allocates an AVFormatContext.
+ * Allocate an AVFormatContext.
  * Can be freed with av_free() but do not forget to free everything you
  * explicitly allocated as well!
  */
 AVFormatContext *avformat_alloc_context(void);
 
 /**
- * Reads packets of a media file to get stream information. This
+ * Read packets of a media file to get stream information. This
  * is useful for file formats with no headers such as MPEG. This
  * function also computes the real framerate in case of MPEG-2 repeat
  * frame mode.
@@ -970,7 +970,7 @@
 int av_find_stream_info(AVFormatContext *ic);
 
 /**
- * Reads a transport packet from a media file.
+ * Read a transport packet from a media file.
  *
  * This function is obsolete and should never be used.
  * Use av_read_frame() instead.
@@ -982,7 +982,7 @@
 int av_read_packet(AVFormatContext *s, AVPacket *pkt);
 
 /**
- * Returns the next frame of a stream.
+ * Return the next frame of a stream.
  *
  * The returned packet is valid
  * until the next av_read_frame() or until av_close_input_file() and
@@ -1003,7 +1003,7 @@
 int av_read_frame(AVFormatContext *s, AVPacket *pkt);
 
 /**
- * Seeks to the keyframe at timestamp.
+ * Seek to the keyframe at timestamp.
  * 'timestamp' in 'stream_index'.
  * @param stream_index If stream_index is (-1), a default
  * stream is selected, and timestamp is automatically converted
@@ -1017,7 +1017,7 @@
                   int flags);
 
 /**
- * Seeks to timestamp ts.
+ * Seek to timestamp ts.
  * Seeking will be done so that the point from which all active streams
  * can be presented successfully will be closest to ts and within min/max_ts.
  * Active streams are all streams that have AVStream.discard < AVDISCARD_ALL.
@@ -1045,33 +1045,33 @@
 int avformat_seek_file(AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
 
 /**
- * Starts playing a network-based stream (e.g. RTSP stream) at the
+ * Start playing a network-based stream (e.g. RTSP stream) at the
  * current position.
  */
 int av_read_play(AVFormatContext *s);
 
 /**
- * Pauses a network-based stream (e.g. RTSP stream).
+ * Pause a network-based stream (e.g. RTSP stream).
  *
  * Use av_read_play() to resume it.
  */
 int av_read_pause(AVFormatContext *s);
 
 /**
- * Frees a AVFormatContext allocated by av_open_input_stream.
+ * Free a AVFormatContext allocated by av_open_input_stream.
  * @param s context to free
  */
 void av_close_input_stream(AVFormatContext *s);
 
 /**
- * Closes a media file (but not its codecs).
+ * Close a media file (but not its codecs).
  *
  * @param s media file handle
  */
 void av_close_input_file(AVFormatContext *s);
 
 /**
- * Adds a new stream to a media file.
+ * Add a new stream to a media file.
  *
  * Can only be called in the read_header() function. If the flag
  * AVFMTCTX_NOHEADER is in the format context, then new streams
@@ -1084,7 +1084,7 @@
 AVProgram *av_new_program(AVFormatContext *s, int id);
 
 /**
- * Adds a new chapter.
+ * Add a new chapter.
  * This function is NOT part of the public API
  * and should ONLY be used by demuxers.
  *
@@ -1100,7 +1100,7 @@
                           int64_t start, int64_t end, const char *title);
 
 /**
- * Sets the pts for a given stream.
+ * Set the pts for a given stream.
  *
  * @param s stream
  * @param pts_wrap_bits number of bits effectively used by the pts
@@ -1119,7 +1119,7 @@
 int av_find_default_stream_index(AVFormatContext *s);
 
 /**
- * Gets the index for a specific timestamp.
+ * Get the index for a specific timestamp.
  * @param flags if AVSEEK_FLAG_BACKWARD then the returned index will correspond
  *                 to the timestamp which is <= the requested one, if backward
  *                 is 0, then it will be >=
@@ -1129,7 +1129,7 @@
 int av_index_search_timestamp(AVStream *st, int64_t timestamp, int flags);
 
 /**
- * Ensures the index uses less memory than the maximum specified in
+ * Ensure the index uses less memory than the maximum specified in
  * AVFormatContext.max_index_size by discarding entries if it grows
  * too large.
  * This function is not part of the public API and should only be called
@@ -1138,7 +1138,7 @@
 void ff_reduce_index(AVFormatContext *s, int stream_index);
 
 /**
- * Adds an index entry into a sorted list. Updates the entry if the list
+ * Add an index entry into a sorted list. Update the entry if the list
  * already contains it.
  *
  * @param timestamp timestamp in the time base of the given stream
@@ -1147,7 +1147,7 @@
                        int size, int distance, int flags);
 
 /**
- * Does a binary search using av_index_search_timestamp() and
+ * Perform a binary search using av_index_search_timestamp() and
  * AVCodec.read_timestamp().
  * This is not supposed to be called directly by a user application,
  * but by demuxers.
@@ -1158,7 +1158,7 @@
                          int64_t target_ts, int flags);
 
 /**
- * Updates cur_dts of all streams based on the given timestamp and AVStream.
+ * Update cur_dts of all streams based on the given timestamp and AVStream.
  *
  * Stream ref_st unchanged, others set cur_dts in their native time base.
  * Only needed for timestamp wrapping or if (dts not set and pts!=dts).
@@ -1168,7 +1168,7 @@
 void av_update_cur_dts(AVFormatContext *s, AVStream *ref_st, int64_t timestamp);
 
 /**
- * Does a binary search using read_timestamp().
+ * Perform a binary search using read_timestamp().
  * This is not supposed to be called directly by a user application,
  * but by demuxers.
  * @param target_ts target timestamp in the time base of the given stream
@@ -1211,7 +1211,7 @@
                   const char *url);
 
 /**
- * Allocates the stream private data and writes the stream header to an
+ * Allocate the stream private data and write the stream header to an
  * output media file.
  *
  * @param s media file handle
@@ -1220,7 +1220,7 @@
 int av_write_header(AVFormatContext *s);
 
 /**
- * Writes a packet to an output media file.
+ * Write a packet to an output media file.
  *
  * The packet shall contain one audio or video frame.
  * The packet must be correctly interleaved according to the container
@@ -1234,7 +1234,7 @@
 int av_write_frame(AVFormatContext *s, AVPacket *pkt);
 
 /**
- * Writes a packet to an output media file ensuring correct interleaving.
+ * Write a packet to an output media file ensuring correct interleaving.
  *
  * The packet must contain one audio or video frame.
  * If the packets are already correctly interleaved, the application should
@@ -1251,7 +1251,7 @@
 int av_interleaved_write_frame(AVFormatContext *s, AVPacket *pkt);
 
 /**
- * Interleaves a packet per dts in an output media file.
+ * Interleave a packet per dts in an output media file.
  *
  * Packets with pkt->destruct == av_destruct_packet will be freed inside this
  * function, so they cannot be used after it. Note that calling av_free_packet()
@@ -1269,7 +1269,7 @@
                                  AVPacket *pkt, int flush);
 
 /**
- * Writes the stream trailer to an output media file and frees the
+ * Write the stream trailer to an output media file and free the
  * file private data.
  *
  * May only be called after a successful call to av_write_header.
@@ -1286,14 +1286,14 @@
 
 #if LIBAVFORMAT_VERSION_MAJOR < 53
 /**
- * Parses width and height out of string str.
+ * Parse width and height out of string str.
  * @deprecated Use av_parse_video_frame_size instead.
  */
 attribute_deprecated int parse_image_size(int *width_ptr, int *height_ptr,
                                           const char *str);
 
 /**
- * Converts framerate from a string to a fraction.
+ * Convert framerate from a string to a fraction.
  * @deprecated Use av_parse_video_frame_rate instead.
  */
 attribute_deprecated int parse_frame_rate(int *frame_rate, int *frame_rate_base,
@@ -1301,7 +1301,7 @@
 #endif
 
 /**
- * Parses datestr and returns a corresponding number of microseconds.
+ * Parse datestr and return a corresponding number of microseconds.
  * @param datestr String representing a date or a duration.
  * - If a date the syntax is:
  * @code
@@ -1312,7 +1312,7 @@
  * interpreted as UTC.
  * If the year-month-day part is not specified it takes the current
  * year-month-day.
- * Returns the number of microseconds since 1st of January, 1970 up to
+ * @return the number of microseconds since 1st of January, 1970 up to
  * the time of the parsed date or INT64_MIN if datestr cannot be
  * successfully parsed.
  * - If a duration the syntax is:
@@ -1320,7 +1320,7 @@
  *  [-]HH[:MM[:SS[.m...]]]
  *  [-]S+[.m...]
  * @endcode
- * Returns the number of microseconds contained in a time interval
+ * @return the number of microseconds contained in a time interval
  * with the specified duration or INT64_MIN if datestr cannot be
  * successfully parsed.
  * @param duration Flag which tells how to interpret datestr, if
@@ -1329,7 +1329,7 @@
  */
 int64_t parse_date(const char *datestr, int duration);
 
-/** Gets the current time in microseconds. */
+/** Get the current time in microseconds. */
 int64_t av_gettime(void);
 
 /* ffm-specific for ffserver */
@@ -1339,7 +1339,7 @@
 void ffm_set_write_index(AVFormatContext *s, int64_t pos, int64_t file_size);
 
 /**
- * Attempts to find a specific tag in a URL.
+ * Attempt to find a specific tag in a URL.
  *
  * syntax: '?tag1=val1&tag2=val2...'. Little URL decoding is done.
  * Return 1 if found.
@@ -1347,7 +1347,7 @@
 int find_info_tag(char *arg, int arg_size, const char *tag1, const char *info);
 
 /**
- * Returns in 'buf' the path with '%d' replaced by a number.
+ * Return in 'buf' the path with '%d' replaced by a number.
  *
  * Also handles the '%0nd' format where 'n' is the total number
  * of digits and '%%'.
@@ -1362,7 +1362,7 @@
                           const char *path, int number);
 
 /**
- * Checks whether filename actually is a numbered sequence generator.
+ * Check whether filename actually is a numbered sequence generator.
  *
  * @param filename possible numbered sequence string
  * @return 1 if a valid numbered sequence string, 0 otherwise
@@ -1370,7 +1370,7 @@
 int av_filename_number_test(const char *filename);
 
 /**
- * Generates an SDP for an RTP session.
+ * Generate an SDP for an RTP session.
  *
  * @param ac array of AVFormatContexts describing the RTP streams. If the
  *           array is composed by only one context, such context can contain
@@ -1386,7 +1386,7 @@
 int avf_sdp_create(AVFormatContext *ac[], int n_files, char *buff, int size);
 
 /**
- * Returns a positive value if the given filename has one of the given
+ * Return a positive value if the given filename has one of the given
  * extensions, 0 otherwise.
  *
  * @param extensions a comma-separated list of filename extensions