changeset 9822:2887f410011f libavcodec

Remove '\p', '\c' and '\e' doxygen markup from doxy, as it should improve plain text doxy readability. See the thread: "[RFC] Should we use doxygen markup?".

--- a/ac3.h	Sat Jun 06 08:46:08 2009 +0000
+++ b/ac3.h	Sat Jun 06 09:35:15 2009 +0000
@@ -132,7 +132,7 @@
 
 /**
  * Calculates the masking curve.
- * First, the excitation is calculated using parameters in \p s and the signal
+ * First, the excitation is calculated using parameters in s and the signal
  * power in each critical band.  The excitation is compared with a predefined
  * hearing threshold table to produce the masking curve.  If delta bit
  * allocation information is provided, it is used for adjusting the masking
@@ -161,7 +161,7 @@
 /**
  * Calculates bit allocation pointers.
  * The SNR is the difference between the masking curve and the signal.  AC-3
- * uses this value for each frequency bin to allocate bits.  The \p snroffset
+ * uses this value for each frequency bin to allocate bits.  The snroffset
  * parameter is a global adjustment to the SNR for all bins.
  *
  * @param[in]  mask       masking curve

--- a/avcodec.h	Sat Jun 06 08:46:08 2009 +0000
+++ b/avcodec.h	Sat Jun 06 09:35:15 2009 +0000
@@ -2544,8 +2544,8 @@
     const AVRational *supported_framerates; ///< array of supported framerates, or NULL if any, array is terminated by {0,0}
     const enum PixelFormat *pix_fmts;       ///< array of supported pixel formats, or NULL if unknown, array is terminated by -1
     /**
-     * Descriptive name for the codec, meant to be more human readable than \p name.
-     * You \e should use the NULL_IF_CONFIG_SMALL() macro to define it.
+     * Descriptive name for the codec, meant to be more human readable than name.
+     * You should use the NULL_IF_CONFIG_SMALL() macro to define it.
      */
     const char *long_name;
     const int *supported_samplerates;       ///< array of supported audio samplerates, or NULL if unknown, array is terminated by 0
@@ -2599,7 +2599,7 @@
      * Meaningful frame information (codec specific) is guaranteed to
      * be parsed at this point. This function is mandatory.
      *
-     * Note that \p buf can be NULL along with \p buf_size set to 0.
+     * Note that buf can be NULL along with buf_size set to 0.
      * Otherwise, this means the whole frame is available at this point.
      *
      * @param avctx the codec context
@@ -2915,15 +2915,15 @@
 void avcodec_set_dimensions(AVCodecContext *s, int width, int height);
 
 /**
- * Returns the pixel format corresponding to the name \p name.
+ * Returns the pixel format corresponding to the name name.
  *
- * If there is no pixel format with name \p name, then looks for a
+ * If there is no pixel format with name name, then looks for a
  * pixel format with the name corresponding to the native endian
- * format of \p name.
+ * format of name.
  * For example in a little-endian system, first looks for "gray16",
  * then for "gray16le".
  *
- * Finally if no pixel format has been found, returns \c PIX_FMT_NONE.
+ * Finally if no pixel format has been found, returns PIX_FMT_NONE.
  */
 enum PixelFormat avcodec_get_pix_fmt(const char* name);
 unsigned int avcodec_pix_fmt_to_codec_tag(enum PixelFormat p);
@@ -2963,7 +2963,7 @@
  * some formats to other formats. avcodec_find_best_pix_fmt() searches which of
  * the given pixel formats should be used to suffer the least amount of loss.
  * The pixel formats from which it chooses one, are determined by the
- * \p pix_fmt_mask parameter.
+ * pix_fmt_mask parameter.
  *
  * @code
  * src_pix_fmt = PIX_FMT_YUV420P;
@@ -3025,7 +3025,7 @@
 /**
  * Initializes libavcodec.
  *
- * @warning This function \e must be called before any other libavcodec
+ * @warning This function must be called before any other libavcodec
  * function.
  */
 void avcodec_init(void);
@@ -3038,7 +3038,7 @@
 #endif
 
 /**
- * Register the codec \p codec and initialize libavcodec.
+ * Register the codec codec and initialize libavcodec.
  *
  * @see avcodec_init()
  */
@@ -3170,7 +3170,7 @@
 
 #if LIBAVCODEC_VERSION_MAJOR < 53
 /**
- * Decodes an audio frame from \p buf into \p samples.
+ * Decodes an audio frame from buf into samples.
  * Wrapper function which calls avcodec_decode_audio3.
  *
  * @deprecated Use avcodec_decode_audio3 instead.
@@ -3192,20 +3192,20 @@
  * Some decoders may support multiple frames in a single AVPacket, such
  * decoders would then just decode the first frame.
  * If no frame
- * could be decompressed, \p frame_size_ptr is zero. Otherwise, it is the
- * decompressed frame size in \e bytes.
+ * could be decompressed, frame_size_ptr is zero. Otherwise, it is the
+ * decompressed frame size in bytes.
  *
- * @warning You \e must set \p frame_size_ptr to the allocated size of the
+ * @warning You must set frame_size_ptr to the allocated size of the
  * output buffer before calling avcodec_decode_audio3().
  *
- * @warning The input buffer must be \c FF_INPUT_BUFFER_PADDING_SIZE larger than
+ * @warning The input buffer must be FF_INPUT_BUFFER_PADDING_SIZE larger than
  * the actual read bytes because some optimized bitstream readers read 32 or 64
  * bits at once and could read over the end.
  *
- * @warning The end of the input buffer \p avpkt->data should be set to 0 to ensure that
+ * @warning The end of the input buffer avpkt->data should be set to 0 to ensure that
  * no overreading happens for damaged MPEG streams.
  *
- * @note You might have to align the input buffer \p avpkt->data and output buffer \p
+ * @note You might have to align the input buffer avpkt->data and output buffer
  * samples. The alignment requirements depend on the CPU: On some CPUs it isn't
  * necessary at all, on others it won't work at all if not aligned and on others
  * it will work but it will have an impact on performance. In practice, the
@@ -3230,7 +3230,7 @@
 
 #if LIBAVCODEC_VERSION_MAJOR < 53
 /**
- * Decodes a video frame from \p buf into \p picture.
+ * Decodes a video frame from buf into picture.
  * Wrapper function which calls avcodec_decode_video2.
  *
  * @deprecated Use avcodec_decode_video2 instead.
@@ -3252,14 +3252,14 @@
  * Some decoders may support multiple frames in a single AVPacket, such
  * decoders would then just decode the first frame.
  *
- * @warning The input buffer must be \c FF_INPUT_BUFFER_PADDING_SIZE larger than
+ * @warning The input buffer must be FF_INPUT_BUFFER_PADDING_SIZE larger than
  * the actual read bytes because some optimized bitstream readers read 32 or 64
  * bits at once and could read over the end.
  *
- * @warning The end of the input buffer \p buf should be set to 0 to ensure that
+ * @warning The end of the input buffer buf should be set to 0 to ensure that
  * no overreading happens for damaged MPEG streams.
  *
- * @note You might have to align the input buffer \p avpkt->data and output buffer \p
+ * @note You might have to align the input buffer avpkt->data and output buffer
  * samples. The alignment requirements depend on the CPU: on some CPUs it isn't
  * necessary at all, on others it won't work at all if not aligned and on others
  * it will work but it will have an impact on performance. In practice, the
@@ -3298,8 +3298,8 @@
 /**
  * Decodes a subtitle message.
  * Returns a negative value on error, otherwise returns the number of bytes used.
- * If no subtitle could be decompressed, \p got_sub_ptr is zero.
- * Otherwise, the subtitle is stored in \p *sub.
+ * If no subtitle could be decompressed, got_sub_ptr is zero.
+ * Otherwise, the subtitle is stored in *sub.
  *
  * @param avctx the codec context
  * @param[out] sub The AVSubtitle in which the decoded subtitle will be stored.
@@ -3314,11 +3314,11 @@
                         uint8_t *buf, int buf_size);
 
 /**
- * Encodes an audio frame from \p samples into \p buf.
+ * Encodes an audio frame from samples into buf.
  *
- * @note The output buffer should be at least \c FF_MIN_BUFFER_SIZE bytes large.
+ * @note The output buffer should be at least FF_MIN_BUFFER_SIZE bytes large.
  * However, for PCM audio the user will know how much space is needed
- * because it depends on the value passed in \p buf_size as described
+ * because it depends on the value passed in buf_size as described
  * below. In that case a lower value can be used.
  *
  * @param avctx the codec context
@@ -3326,9 +3326,9 @@
  * @param[in] buf_size the output buffer size
  * @param[in] samples the input buffer containing the samples
  * The number of samples read from this buffer is frame_size*channels,
- * both of which are defined in \p avctx.
- * For PCM audio the number of samples read from \p samples is equal to
- * \p buf_size * input_sample_size / output_sample_size.
+ * both of which are defined in avctx.
+ * For PCM audio the number of samples read from samples is equal to
+ * buf_size * input_sample_size / output_sample_size.
  * @return On error a negative value is returned, on success zero or the number
  * of bytes used to encode the data read from the input buffer.
  */
@@ -3336,9 +3336,9 @@
                          const short *samples);
 
 /**
- * Encodes a video frame from \p pict into \p buf.
+ * Encodes a video frame from pict into buf.
  * The input picture should be
- * stored using a specific format, namely \c avctx.pix_fmt.
+ * stored using a specific format, namely avctx.pix_fmt.
  *
  * @param avctx the codec context
  * @param[out] buf the output buffer for the bitstream of encoded frame
@@ -3376,7 +3376,7 @@
 /* misc useful functions */
 
 /**
- * Returns a single letter to describe the given picture type \p pict_type.
+ * Returns a single letter to describe the given picture type pict_type.
  *
  * @param[in] pict_type the picture type
  * @return A single character representing the picture type.
@@ -3666,7 +3666,7 @@
 unsigned int av_xiphlacing(unsigned char *s, unsigned int v);
 
 /**
- * Parses \p str and put in \p width_ptr and \p height_ptr the detected values.
+ * Parses str and put in width_ptr and height_ptr the detected values.
  *
  * @return 0 in case of a successful parsing, a negative value otherwise
  * @param[in] str the string to parse: it has to be a string in the format
@@ -3679,7 +3679,7 @@
 int av_parse_video_frame_size(int *width_ptr, int *height_ptr, const char *str);
 
 /**
- * Parses \p str and put in \p frame_rate the detected values.
+ * Parses str and put in frame_rate the detected values.
  *
  * @return 0 in case of a successful parsing, a negative value otherwise
  * @param[in] str the string to parse: it has to be a string in the format
@@ -3710,7 +3710,7 @@
 #define AVERROR_PATCHWELCOME    -MKTAG('P','A','W','E') /**< Not yet implemented in FFmpeg. Patches welcome. */
 
 /**
- * Registers the hardware accelerator \p hwaccel.
+ * Registers the hardware accelerator hwaccel.
  */
 void av_register_hwaccel(AVHWAccel *hwaccel);
 
@@ -3734,7 +3734,7 @@
 
 /**
  * Register a user provided lock manager supporting the operations
- * specified by AVLockOp. \p mutex points to a (void *) where the
+ * specified by AVLockOp. mutex points to a (void *) where the
  * lockmgr should store/get a pointer to a user allocated mutex. It's
  * NULL upon AV_LOCK_CREATE and != NULL for all other ops.
  *

--- a/internal.h	Sat Jun 06 08:46:08 2009 +0000
+++ b/internal.h	Sat Jun 06 09:35:15 2009 +0000
@@ -33,7 +33,7 @@
  * a pointer to an AVClass struct
  * @param[in] feature string containing the name of the missing feature
  * @param[in] want_sample indicates if samples are wanted which exhibit this feature.
- * If \p want_sample is non-zero, additional verbage will be added to the log
+ * If want_sample is non-zero, additional verbage will be added to the log
  * message which tells the user how to report samples to the development
  * mailing list.
  */
@@ -48,13 +48,13 @@
 void ff_log_ask_for_sample(void *avc, const char *msg);
 
 /**
- * Determines whether \p pix_fmt is a hardware accelerated format.
+ * Determines whether pix_fmt is a hardware accelerated format.
  */
 int ff_is_hwaccel_pix_fmt(enum PixelFormat pix_fmt);
 
 /**
- * Returns the hardware accelerated codec for codec \p codec_id and
- * pixel format \p pix_fmt.
+ * Returns the hardware accelerated codec for codec codec_id and
+ * pixel format pix_fmt.
  *
  * @param codec_id the codec to match
  * @param pix_fmt the pixel format to match

--- a/opt.h	Sat Jun 06 08:46:08 2009 +0000
+++ b/opt.h	Sat Jun 06 09:35:15 2009 +0000
@@ -87,8 +87,8 @@
 
 
 /**
- * Looks for an option in \p obj. Looks only for the options which
- * have the flags set as specified in \p mask and \p flags (that is,
+ * Looks for an option in obj. Looks only for the options which
+ * have the flags set as specified in mask and flags (that is,
  * for which it is the case that opt->flags & mask == flags).
  *
  * @param[in] obj a pointer to a struct whose first element is a
@@ -108,7 +108,7 @@
 
 /**
  * @return a pointer to the AVOption corresponding to the field set or
- * NULL if no matching AVOption exists, or if the value \p val is not
+ * NULL if no matching AVOption exists, or if the value val is not
  * valid
  * @see av_set_string3()
  */

--- a/pixdesc.h	Sat Jun 06 08:46:08 2009 +0000
+++ b/pixdesc.h	Sat Jun 06 09:35:15 2009 +0000
@@ -86,8 +86,8 @@
 extern const AVPixFmtDescriptor av_pix_fmt_descriptors[];
 
 /**
- * Reads a line from an image, and writes to \p dst the values of the
- * pixel format component \p c.
+ * Reads a line from an image, and writes to dst the values of the
+ * pixel format component c.
  *
  * @param data the array containing the pointers to the planes of the image
  * @param linesizes the array containing the linesizes of the image
@@ -95,10 +95,10 @@
  * @param x the horizontal coordinate of the first pixel to read
  * @param y the vertical coordinate of the first pixel to read
  * @param w the width of the line to read, that is the number of
- * values to write to \p dst
+ * values to write to dst
  * @param read_pal_component if not zero and the format is a paletted
- * format writes to \p dst the values corresponding to the palette
- * component \p c in data[1], rather than the palette indexes in
+ * format writes to dst the values corresponding to the palette
+ * component c in data[1], rather than the palette indexes in
  * data[0]. The behavior is undefined if the format is not paletted.
  */
 static inline void read_line(uint16_t *dst, const uint8_t *data[4], const int linesize[4],

--- a/put_bits.h	Sat Jun 06 08:46:08 2009 +0000
+++ b/put_bits.h	Sat Jun 06 09:35:15 2009 +0000
@@ -52,10 +52,10 @@
 } PutBitContext;
 
 /**
- * Initializes the PutBitContext \p s.
+ * Initializes the PutBitContext s.
  *
  * @param buffer the buffer where to put bits
- * @param buffer_size the size in bytes of \p buffer
+ * @param buffer_size the size in bytes of buffer
  */
 static inline void init_put_bits(PutBitContext *s, uint8_t *buffer, int buffer_size)
 {
@@ -123,16 +123,16 @@
 void align_put_bits(PutBitContext *s);
 
 /**
- * Puts the string \p s in the bitstream.
+ * Puts the string s in the bitstream.
  *
  * @param terminate_string 0-terminates the written string if value is 1
  */
 void ff_put_string(PutBitContext * pbc, const char *s, int terminate_string);
 
 /**
- * Copies the content of \p src to the bitstream.
+ * Copies the content of src to the bitstream.
  *
- * @param length the number of bits of \p src to copy
+ * @param length the number of bits of src to copy
  */
 void ff_copy_bits(PutBitContext *pb, const uint8_t *src, int length);
 
@@ -290,7 +290,7 @@
 /**
  * Skips the given number of bits.
  * Must only be used if the actual values in the bitstream do not matter.
- * If \p n is 0 the behavior is undefined.
+ * If n is 0 the behavior is undefined.
  */
 static inline void skip_put_bits(PutBitContext *s, int n){
 #ifdef ALT_BITSTREAM_WRITER