[NUT-devel] [nut]: r535 - src/trunk/libnut/libnut.h
diego
subversion at mplayerhq.hu
Fri Feb 1 16:17:58 CET 2008
Author: diego
Date: Fri Feb 1 16:17:57 2008
New Revision: 535
Log:
doxygen comment review, part II
Modified:
src/trunk/libnut/libnut.h
Modified: src/trunk/libnut/libnut.h
==============================================================================
--- src/trunk/libnut/libnut.h (original)
+++ src/trunk/libnut/libnut.h Fri Feb 1 16:17:57 2008
@@ -240,11 +240,11 @@ int nut_seek(nut_context_t * nut, double
* \author Oded Shimon <ods15 at ods15.dyndns.org>
* \date 2005-2006
*
- * Reference implementation for NUT open container format.
+ * Reference implementation for the NUT open container format.
*
* libnut source code is at svn://svn.mplayerhq.hu/nut/src/libnut/
*
- * Copyright of this library is MIT/X license. For more details, see
+ * This library is covered by the MIT/X license. For more details, see
* \ref License.
*
* For more information on the format, please visit http://www.nut-container.org/
@@ -255,7 +255,7 @@ int nut_seek(nut_context_t * nut, double
*/
/*! \struct nut_alloc_t
- * libc semantics are assumed to all functions. (realloc must work with NULL or zero size)
+ * libc semantics are assumed for all functions (realloc must work with NULL or zero size).
*
* #malloc function pointer may be NULL. This indicates using libc malloc, realloc and free functions.
*
@@ -288,34 +288,34 @@ int nut_seek(nut_context_t * nut, double
/*! \var char nut_info_field_t::type[7]
* Type of field value
- * - "v" - Integer value
- * - "s" - Signed integer value
- * - "r" - Fraction rational
- * - "t" - Timestamp
+ * - "v" - integer value
+ * - "s" - signed integer value
+ * - "r" - fraction rational
+ * - "t" - timestamp
* - "UTF-8" - UTF-8 coded string
- * - Other - Binary data
+ * - Other - binary data
*/
/*! \var int64_t nut_info_field_t::val
- * - "v" - Integer value
- * - "s" - Integer value
- * - "r" - Numerator of fraction
- * - "t" - Integer timestamp in timebase #tb
- * - Other - Length of #data in bytes
+ * - "v" - integer value
+ * - "s" - integer value
+ * - "r" - numerator of fraction
+ * - "t" - integer timestamp in timebase #tb
+ * - Other - length of #data in bytes
*
- * In the case of UTF-8 string, length of #data \b must \b not contain the
+ * In the case an of UTF-8 string, length of #data \b must \b not contain the
* terminating NUL (U+0000).
*/
/*! \var nut_timebase_t nut_info_field_t::tb
- * In the case of muxer, values of #tb \b must be identical to the
+ * In the muxer case, values of #tb \b must be identical to the
* timebase of one of the streams.
*/
/*! \var uint8_t * nut_info_field_t::data
- * Even in the case of UTF-8 string, this data is \b not NULL terminated.
+ * Even in the case of an UTF-8 string, this data is \b not NULL terminated.
*
- * For muxer, this value \b must be NULL if info field carries no binary
+ * For the muxer, this value \b must be NULL if info field carries no binary
* data.
*/
@@ -325,21 +325,21 @@ int nut_seek(nut_context_t * nut, double
*/
/*! \var nut_info_packet_t::chapter_id
- * Value of 0 indicates info packet applies to complete file.
+ * A value of 0 indicates that the info packet applies to the complete file.
*
* Positive values are real chapters. Real chapters must not overlap. The
* #chapter_id of a real chapter must not be higher than the total amount
* of real chapters in the file.
*
- * Negative values indicate a subsection of file and may overlap.
+ * Negative values indicate a file subsection and may overlap.
*
- * If #chapter_id is 0, #chapter_start and #chapter_len provide length of
- * entire file.
+ * If #chapter_id is 0, #chapter_start and #chapter_len provide the length
+ * of the entire file.
*/
/*! \var nut_info_packet_t::chapter_tb
- * In muxing, values #chapter_tb \b must be identical to the timebase of
- * one of the streams
+ * When muxing, values #chapter_tb \b must be identical to the timebase of
+ * one of the streams.
*/
/*!
@@ -356,25 +356,25 @@ int nut_seek(nut_context_t * nut, double
* - 4096 FLAG_CODED
* - 8192 FLAG_INVALID
*
- * Last entry of frame table \b must have flag==-1.
+ * The last entry of nut_frame_table_input_t \b must have flag == -1.
*/
/*! \fn nut_context_t * nut_muxer_init(const nut_muxer_opts_t * mopts, const nut_stream_header_t s[], const nut_info_packet_t info[])
- * \param mopts Muxer options
- * \param s Stream header data, terminated by \a type=-1.
- * \param info Info packet data, terminated by \a count=-1. May be \a NULL.
+ * \param mopts muxer options
+ * \param s Stream header data, terminated by \a type = -1.
+ * \param info Info packet data, terminated by \a count = -1. May be \a NULL.
* \return NUT muxer context
*
- * In case nut_muxer_opts_t::realtime_stream is set, the first packet given
- * to the nut_output_stream_t::write() function given by muxer options will
- * be all of the main headers. This packet must be given exactly once at
- * the begginning of any stream forwarded out.
+ * In case nut_muxer_opts_t::realtime_stream is set, the first packet passed
+ * to the nut_output_stream_t::write() function will be all of the main
+ * headers. This packet must be passed along exactly once with the
+ * beginning of any stream forwarded out.
*/
/*! \fn void nut_muxer_uninit(nut_context_t *nut)
* \param nut NUT muxer context
*
- * Optionally writes index if nut_muxer_opts_t::write_index is set and
+ * Optionaly writes index if nut_muxer_opts_t::write_index is set and
* nut_muxer_opts_t::realtime_stream is unset.
*
* \warning Must \b not be used directly if nut_write_frame_reorder() was used.
@@ -383,12 +383,12 @@ int nut_seek(nut_context_t * nut, double
/*! \fn void nut_write_frame(nut_context_t * nut, const nut_packet_t * p, const uint8_t * buf)
* \param nut NUT muxer context
- * \param p Infomation on the frame written.
- * \param buf Actual data of frame.
+ * \param p information about the frame
+ * \param buf actual frame data
*
* If nut_muxer_opts_t::realtime_stream realtime_stream is unset, repeated
* headers will be written at some positions. Syncpoints will be written in
- * accordance to NUT spec. If nut_muxer_opts_t::realtime_stream is set,
+ * accordance to the NUT spec. If nut_muxer_opts_t::realtime_stream is set,
* calling this function will result in a single nut_output_stream_t::write()
* call, which will be the full frame NUT packet. If the packet starts with
* a syncpoint startcode, it may be used as a start point after giving the
@@ -403,17 +403,17 @@ int nut_seek(nut_context_t * nut, double
/*! \fn void nut_write_info(nut_context_t * nut, const nut_info_packet_t * info)
* \param nut NUT muxer context
- * \param info A single info packet.
+ * \param info a single info packet
*
- * The use of this function is \b illegal in non realtime streams, and will
+ * The use of this function is \b illegal in non-realtime streams, and will
* do nothing if nut_muxer_opts_t::realtime_stream is not set. The result
* is a single call to nut_output_stream_t::write() with the NUT info packet.
*/
/*! \fn void nut_write_frame_reorder(nut_context_t * nut, const nut_packet_t * p, const uint8_t * buf)
* \param nut NUT muxer context
- * \param p Infomation on the frame written.
- * \param buf Actual data of frame.
+ * \param p information about the frame
+ * \param buf actual frame data
*
* Uses an internal buffer and sorts the frames to meet NUT's ordering rule.
* Calls to this function \b must \b not be mixed with calls to
@@ -431,10 +431,10 @@ int nut_seek(nut_context_t * nut, double
*/
/*! \fn void nut_framecode_generate(const nut_stream_header_t s[], nut_frame_table_input_t fti[256])
- * \param s Stream header data, terminated by \a type=-1.
- * \param fti Output framecode table data. Must be pre-allocated to 256 entries.
+ * \param s Stream header data, terminated by \a type = -1.
+ * \param fti Output framecode table data, must be preallocated to 256 entries.
*
- * Creates an optimized framecode table for NUT main header based on stream
+ * Creates an optimized framecode table for the NUT main header based on stream
* types and codecs. Currently recognized fourcc values are "mp4v", "h264",
* "mp3 ", and "vrbs".
*
@@ -445,10 +445,10 @@ int nut_seek(nut_context_t * nut, double
/*! \addtogroup demuxer
* All of the demuxer related functions return an integer value
* representing one of the following return codes:
- * - 0 (=#NUT_ERR_NO_ERROR) Success
- * - #NUT_ERR_EOF Unexpected or expected EOF
- * - #NUT_ERR_EAGAIN Insufficient data for demuxing
- * - #NUT_ERR_NOT_SEEKABLE Unsuccessful seek in nut_seek()
+ * - 0 (=#NUT_ERR_NO_ERROR) success
+ * - #NUT_ERR_EOF unexpected or expected EOF
+ * - #NUT_ERR_EAGAIN insufficient data for demuxing
+ * - #NUT_ERR_NOT_SEEKABLE unsuccessful seek in nut_seek()
*
* \par NUT_ERR_EOF
* If any function returns EOF, it can be recovered by using nut_seek().
@@ -456,18 +456,18 @@ int nut_seek(nut_context_t * nut, double
* error and only nut_demuxer_uninit() can be called.
*
* \par NUT_ERR_EAGAIN
- * Indicates not enough data was given from nut_input_stream_t::read()
- * function, but EOF was not met. Whichever function returned this should
- * be re-called given the exact same params when more data is available.
+ * Indicates that not enough data was returned by nut_input_stream_t::read(),
+ * but EOF was not reached. Whichever function returned this should be called
+ * again with the exact same parameters when more data is available.
* The exception to this is nut_read_frame(), which should be called with
- * an updated \a buf param.
+ * an updated \a buf parameter.
*
* \par NUT_ERR_NOT_SEEKABLE
* Can only be returned from nut_seek(). Indicates that no seek has been
- * performed and that the stream is in the exact same position before the
- * seek.
+ * performed and that the stream is in the exact same position it was in
+ * before the seek.
*
- * \par Other errors
+ * \par other errors
* All errors except the list above are fatal.
* The only legal operation after a fatal error is nut_demuxer_uninit().
*/
@@ -484,7 +484,7 @@ int nut_seek(nut_context_t * nut, double
* nut_seek() with an unseekable stream will yield #NUT_ERR_NOT_SEEKABLE
*
* Parameter whence must support the following libc defines:
- * - SEEK_SET - pos is used as offset from begginning of file
+ * - SEEK_SET - pos is used as offset from beginning of file
* - SEEK_CUR - pos is used as offset from current position
* - SEEK_END - pos is used as offset from end of file
*/
@@ -502,7 +502,7 @@ int nut_seek(nut_context_t * nut, double
*/
/*! \var off_t nut_input_stream_t::file_pos
- * Must contain position in file at begginning of demuxing. Should
+ * Must contain the position in the file at which demuxing begins. Should
* usually be zero.
*/
@@ -511,33 +511,33 @@ int nut_seek(nut_context_t * nut, double
* \param s Pointer to stream header variable to be set to an array
* \param info Pointer to info header variable, may be NULL.
*
- * Both `s' and `info' are handeled by context, and are illegal pointers
+ * Both `s' and `info' are handled by context and are illegal pointers
* after nut_demuxer_uninit().
*
- * If main NUT headers are not found at begginning of file and the input
- * stream is seekable, Several parts of the file are searched for the main
+ * If main NUT headers are not found at beginning of file and the input
+ * stream is seekable, several parts of the file are searched for the main
* headers before giving up in accordance to NUT spec (EOF and 2^n
* locations).
*
* Any error returned from this function except #NUT_ERR_EAGAIN is fatal.
- * No other functions may be called until a successful call to
- * nut_read_headers().
+ * No other functions may be called before a call to
+ * nut_read_headers() succeeds.
*/
/*! \fn int nut_read_next_packet(nut_context_t * nut, nut_packet_t * pd)
* \param nut NUT demuxer context
* \param pd Pointer to frame header struct to be filled with next frame
- * info.
+ * information.
*
* After a successful call to nut_read_next_packet(), nut_read_frame()
* \b must be called.
*
* If nut_demuxer_opts_t::new_info is non-NULL, a new info packet may be
- * seen before decoding of frame header and this function pointer will be
+ * seen before decoding the frame header and this function pointer will be
* called (possibly even several times).
*
- * If a stream error is detected during decoding of frame header,
- * nut_read_next_packet() will attempt to recover from the error and gives
+ * If a stream error is detected during frame header decoding,
+ * nut_read_next_packet() will attempt to recover from the error and return
* the next undamaged frame in the stream.
*/
@@ -548,11 +548,11 @@ int nut_seek(nut_context_t * nut, double
*
* This function must be called \b after nut_read_next_packet().
*
- * If the function return #NUT_ERR_EAGAIN or #NUT_ERR_EOF, \a len will
+ * If the function returns #NUT_ERR_EAGAIN or #NUT_ERR_EOF, \a len will
* return the amount of bytes actually read.
*
- * Data is always written to the \b begginning of the buffer \a buf, so it
- * must be moved accordingly in case of beign called again for
+ * Data is always written to the \b beginning of the buffer \a buf, so it
+ * must be moved accordingly in case of being called again for
* #NUT_ERR_EAGAIN.
*
* \par Example:
@@ -566,14 +566,14 @@ int nut_seek(nut_context_t * nut, double
/*! \fn int nut_seek(nut_context_t * nut, double time_pos, int flags, const int * active_streams)
* \param nut NUT demuxer context
- * \param time_pos Position to seek to in seconds
- * \param flags Bitfield given as seek options.
- * \param active_streams -1 terminated list of all streams that are active.
- * May be NULL - indicates all streams are active.
+ * \param time_pos position to seek to in seconds
+ * \param flags bitfield with seek options
+ * \param active_streams List of all active streams terminated by -1,
+ * may be NULL indicating that all streams are active.
*
* Flag bitfield options:
* - 1 RELATIVE: If set, \a time_pos is relative to current position,
- * otherwise it is absoloute.
+ * otherwise it is absolute.
* - 2 FORWARD: If set, the seek should find the nearest keyframe
* after the target position. If unset, the nearest
* keyframe before the target position is picked.
@@ -582,12 +582,12 @@ int nut_seek(nut_context_t * nut, double
* backwards seeking, a keyframe for all active streams is garunteed to be
* found before the target presentation timestamp.
*
- * In forward seeking, no percise seeking is preformed. The function seeks
+ * In forward seeking, no precise seeking is performed. The function seeks
* to the first keyframe for an active stream after the target timestamp.
*
* If the function returns #NUT_ERR_NOT_SEEKABLE, no seek was performed.
- * If #NUT_ERR_EOF is returned, requested position is outside bounds of
- * file.
+ * If #NUT_ERR_EOF is returned, the requested position is outside the
+ * bounds of the file.
*
* After nut_seek, nut_read_next_packet should be called to get the next frame.
*/
More information about the NUT-devel
mailing list