ref: 1b951961ef9f7bd8cdf7da2a1cb927be71a2b230
parent: 35d4fb78eafc6aa738919a8c4984744e1bcf52d9
author: Ralph Giles <[email protected]>
date: Wed Sep 7 06:40:25 EDT 2011
Add minimal doxygen markup to the public headers. Doxygen uses comments in the source code to generate documentation. This commit just adds the descriptive headers and marks current comments and appropriate for inclusion in the API docs. Many symbols remain undocumented. See the warnings from the build output.
--- a/libcelt/opus_defines.h
+++ b/libcelt/opus_defines.h
@@ -25,6 +25,11 @@
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
+/**
+ * @file opus_defines.h
+ * @brief Opus reference implementation constants
+ */
+
#ifndef OPUS_DEFINES_H
#define OPUS_DEFINES_H
@@ -56,7 +61,10 @@
#define __opus_check_int_ptr(ptr) ((ptr) + ((ptr) - (opus_int32*)(ptr)))
#define __opus_check_uint_ptr(ptr) ((ptr) + ((ptr) - (opus_uint32*)(ptr)))
-/* Error codes */
+/** \defgroup errorcodes Error codes
+ * @{+ */
+
/** No error */
#define OPUS_OK 0
/** An (or more) invalid argument (e.g. out of range) */
@@ -74,7 +82,9 @@
/** Memory allocation has failed */
#define OPUS_ALLOC_FAIL -7
+/* @} */
+
#define OPUS_BITRATE_AUTO -2
#define OPUS_BITRATE_MAX -1
@@ -93,19 +103,19 @@
#define OPUS_BANDWIDTH_FULLBAND 1105
-/* OPUS_APPLICATION_VOIP or OPUS_APPLICATION_AUDIO */
+/** OPUS_APPLICATION_VOIP or OPUS_APPLICATION_AUDIO */
#define OPUS_SET_APPLICATION_REQUEST 4000
#define OPUS_SET_APPLICATION(x) OPUS_SET_APPLICATION_REQUEST, __opus_check_int(x)
#define OPUS_GET_APPLICATION_REQUEST 4001
#define OPUS_GET_APPLICATION(x) OPUS_GET_APPLICATION_REQUEST, __opus_check_int_ptr(x)
-/* Coding bit-rate in bit/second */
+/** Coding bit-rate in bit/second */
#define OPUS_SET_BITRATE_REQUEST 4002
#define OPUS_SET_BITRATE(x) OPUS_SET_BITRATE_REQUEST, __opus_check_int(x)
#define OPUS_GET_BITRATE_REQUEST 4003
#define OPUS_GET_BITRATE(x) OPUS_GET_BITRATE_REQUEST, __opus_check_int_ptr(x)
-/* 0 for CBR, 1 for VBR */
+/** 0 for CBR, 1 for VBR */
#define OPUS_SET_VBR_REQUEST 4006
#define OPUS_SET_VBR(x) OPUS_SET_VBR_REQUEST, __opus_check_int(x)
#define OPUS_GET_VBR_REQUEST 4007
@@ -161,8 +171,8 @@
#define OPUS_RESET_STATE 4028
-/* For testing purposes: the encoder and decoder state should
- always be identical after coding a payload */
+/** For testing purposes: the encoder and decoder state should
+ always be identical after coding a payload */
#define OPUS_GET_FINAL_RANGE_REQUEST 4031
#define OPUS_GET_FINAL_RANGE(x) OPUS_GET_FINAL_RANGE_REQUEST, __opus_check_uint_ptr(x)
@@ -177,4 +187,4 @@
}
#endif
-#endif /* OPUS_H */
+#endif /* OPUS_DEFINES_H */
--- a/libcelt/opus_types.h
+++ b/libcelt/opus_types.h
@@ -28,7 +28,7 @@
/**
@file opus_types.h
- @brief OPUS types
+ @brief Opus reference implementation types
*/
#ifndef _OPUS_TYPES_H
#define _OPUS_TYPES_H
--- a/src/opus.h
+++ b/src/opus.h
@@ -25,6 +25,11 @@
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
+/**
+ * @file opus.h
+ * @brief Opus reference implementation API
+ */
+
#ifndef OPUS_H
#define OPUS_H
@@ -44,7 +49,7 @@
OPUS_EXPORT int opus_encoder_get_size(int channels);
-/*
+/**
* There are two coding modes:
* OPUS_APPLICATION_VOIP gives best quality at a given bitrate for voice
* signals. It enhances the input signal by high-pass filtering and
@@ -58,37 +63,37 @@
* than 15 ms of coding delay.
*/
-/* Returns initialized encoder state */
+/** Returns initialized encoder state */
OPUS_EXPORT OpusEncoder *opus_encoder_create(
- opus_int32 Fs, /* Sampling rate of input signal (Hz) */
- int channels, /* Number of channels (1/2) in input signal */
- int application, /* Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
- int *error /* Error code */
+ opus_int32 Fs, /**< Sampling rate of input signal (Hz) */
+ int channels, /**< Number of channels (1/2) in input signal */
+ int application, /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
+ int *error /**< Error code */
);
OPUS_EXPORT int opus_encoder_init(
- OpusEncoder *st, /* Encoder state */
- opus_int32 Fs, /* Sampling rate of input signal (Hz) */
- int channels, /* Number of channels (1/2) in input signal */
- int application /* Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
+ OpusEncoder *st, /**< Encoder state */
+ opus_int32 Fs, /**< Sampling rate of input signal (Hz) */
+ int channels, /**< Number of channels (1/2) in input signal */
+ int application /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
);
-/* Returns length of the data payload (in bytes) */
+/** Returns length of the data payload (in bytes) */
OPUS_EXPORT int opus_encode(
- OpusEncoder *st, /* Encoder state */
- const opus_int16 *pcm, /* Input signal (interleaved if 2 channels). length is frame_size*channels */
- int frame_size, /* Number of samples per frame of input signal */
- unsigned char *data, /* Output payload (no more than max_data_bytes long) */
- int max_data_bytes /* Allocated memory for payload; don't use for controlling bitrate */
+ OpusEncoder *st, /**< Encoder state */
+ const opus_int16 *pcm, /**< Input signal (interleaved if 2 channels). length is frame_size*channels */
+ int frame_size, /**< Number of samples per frame of input signal */
+ unsigned char *data, /**< Output payload (no more than max_data_bytes long) */
+ int max_data_bytes /**< Allocated memory for payload; don't use for controlling bitrate */
);
-/* Returns length of the data payload (in bytes) */
+/** Returns length of the data payload (in bytes) */
OPUS_EXPORT int opus_encode_float(
- OpusEncoder *st, /* Encoder state */
- const float *pcm, /* Input signal (interleaved if 2 channels). length is frame_size*channels 0dbFS range of +/-1.0*/
- int frame_size, /* Number of samples per frame of input signal */
- unsigned char *data, /* Output payload (no more than max_data_bytes long) */
- int max_data_bytes /* Allocated memory for payload; don't use for controlling bitrate */
+ OpusEncoder *st, /**< Encoder state */
+ const float *pcm, /**< Input signal (interleaved if 2 channels). length is frame_size*channels 0dbFS range of +/-1.0*/
+ int frame_size, /**< Number of samples per frame of input signal */
+ unsigned char *data, /**< Output payload (no more than max_data_bytes long) */
+ int max_data_bytes /**< Allocated memory for payload; don't use for controlling bitrate */
);
OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
@@ -100,36 +105,36 @@
OPUS_EXPORT int opus_decoder_get_size(int channels);
OPUS_EXPORT OpusDecoder *opus_decoder_create(
- opus_int32 Fs, /* Sampling rate of output signal (Hz) */
- int channels, /* Number of channels (1/2) in output signal */
- int *error /* Error code*/
+ opus_int32 Fs, /**< Sampling rate of output signal (Hz) */
+ int channels, /**< Number of channels (1/2) in output signal */
+ int *error /**< Error code*/
);
OPUS_EXPORT int opus_decoder_init(OpusDecoder *st,
- opus_int32 Fs, /* Sampling rate of output signal (Hz) */
- int channels /* Number of channels (1/2) in output signal */
+ opus_int32 Fs, /**< Sampling rate of output signal (Hz) */
+ int channels /**< Number of channels (1/2) in output signal */
);
-/* Returns the number of samples decoded or a negative error code */
+/** Returns the number of samples decoded or a negative error code */
OPUS_EXPORT int opus_decode(
- OpusDecoder *st, /* Decoder state */
- const unsigned char *data, /* Input payload. Use a NULL pointer to indicate packet loss */
- int len, /* Number of bytes in payload */
- opus_int16 *pcm, /* Output signal (interleaved if 2 channels). length is frame_size*channels */
- int frame_size, /* Number of samples per frame of input signal */
- int decode_fec /* Flag (0/1) to request that any in-band forward error correction data be */
- /* decoded. If no such data is available the frame is decoded as if it were lost. */
+ OpusDecoder *st, /**< Decoder state */
+ const unsigned char *data, /**< Input payload. Use a NULL pointer to indicate packet loss */
+ int len, /**< Number of bytes in payload */
+ opus_int16 *pcm, /**< Output signal (interleaved if 2 channels). length is frame_size*channels */
+ int frame_size, /**< Number of samples per frame of input signal */
+ int decode_fec /**< Flag (0/1) to request that any in-band forward error correction data be */
+ /**< decoded. If no such data is available the frame is decoded as if it were lost. */
);
-/* Returns the number of samples decoded or a negative error code */
+/** Returns the number of samples decoded or a negative error code */
OPUS_EXPORT int opus_decode_float(
- OpusDecoder *st, /* Decoder state */
- const unsigned char *data, /* Input payload. Use a NULL pointer to indicate packet loss */
- int len, /* Number of bytes in payload */
- float *pcm, /* Output signal (interleaved if 2 channels). length is frame_size*channels 0dbFS range of -/+1.0*/
- int frame_size, /* Number of samples per frame of input signal */
- int decode_fec /* Flag (0/1) to request that any in-band forward error correction data be */
- /* decoded. If no such data is available the frame is decoded as if it were lost. */
+ OpusDecoder *st, /**< Decoder state */
+ const unsigned char *data, /**< Input payload. Use a NULL pointer to indicate packet loss */
+ int len, /**< Number of bytes in payload */
+ float *pcm, /**< Output signal (interleaved if 2 channels). length is frame_size*channels 0dbFS range of -/+1.0*/
+ int frame_size, /**< Number of samples per frame of input signal */
+ int decode_fec /**< Flag (0/1) to request that any in-band forward error correction data be */
+ /**< decoded. If no such data is available the frame is decoded as if it were lost. */
);
OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...);
@@ -147,7 +152,7 @@
OPUS_EXPORT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsigned char packet[], int len);
-/* Repacketizer */
+/** Repacketizer */
typedef struct OpusRepacketizer OpusRepacketizer;
OPUS_EXPORT int opus_repacketizer_get_size(void);
--- a/src/opus_multistream.h
+++ b/src/opus_multistream.h
@@ -25,6 +25,10 @@
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
+/**
+ * @file opus_multistream.h
+ * @brief Opus reference implementation multistream API
+ */
#ifndef OPUS_MULTISTREAM_H
#define OPUS_MULTISTREAM_H
@@ -35,41 +39,41 @@
typedef struct OpusMSDecoder OpusMSDecoder;
OPUS_EXPORT OpusMSEncoder *opus_multistream_encoder_create(
- int Fs, /* Sampling rate of input signal (Hz) */
- int channels, /* Number of channels (1/2) in input signal */
+ int Fs, /**< Sampling rate of input signal (Hz) */
+ int channels, /**< Number of channels (1/2) in input signal */
int streams,
int coupled_streams,
unsigned char *mapping,
- int application, /* Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
- int *error /* Error code */
+ int application, /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
+ int *error /**< Error code */
);
OPUS_EXPORT int opus_multistream_encoder_init(
- OpusMSEncoder *st, /* Encoder state */
- int Fs, /* Sampling rate of input signal (Hz) */
- int channels, /* Number of channels (1/2) in input signal */
+ OpusMSEncoder *st, /**< Encoder state */
+ int Fs, /**< Sampling rate of input signal (Hz) */
+ int channels, /**< Number of channels (1/2) in input signal */
int streams,
int coupled_streams,
unsigned char *mapping,
- int application /* Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
+ int application /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
);
-/* Returns length of the data payload (in bytes) */
+/** Returns length of the data payload (in bytes) */
OPUS_EXPORT int opus_multistream_encode(
- OpusMSEncoder *st, /* Encoder state */
- const opus_int16 *pcm, /* Input signal (interleaved if 2 channels). length is frame_size*channels */
- int frame_size, /* Number of samples per frame of input signal */
- unsigned char *data, /* Output payload (no more than max_data_bytes long) */
- int max_data_bytes /* Allocated memory for payload; don't use for controlling bitrate */
+ OpusMSEncoder *st, /**< Encoder state */
+ const opus_int16 *pcm, /**< Input signal (interleaved if 2 channels). length is frame_size*channels */
+ int frame_size, /**< Number of samples per frame of input signal */
+ unsigned char *data, /**< Output payload (no more than max_data_bytes long) */
+ int max_data_bytes /**< Allocated memory for payload; don't use for controlling bitrate */
);
-/* Returns length of the data payload (in bytes) */
+/** Returns length of the data payload (in bytes) */
OPUS_EXPORT int opus_multistream_encode_float(
- OpusMSEncoder *st, /* Encoder state */
- const float *pcm, /* Input signal (interleaved if 2 channels). length is frame_size*channels */
- int frame_size, /* Number of samples per frame of input signal */
- unsigned char *data, /* Output payload (no more than max_data_bytes long) */
- int max_data_bytes /* Allocated memory for payload; don't use for controlling bitrate */
+ OpusMSEncoder *st, /**< Encoder state */
+ const float *pcm, /**< Input signal (interleaved if 2 channels). length is frame_size*channels */
+ int frame_size, /**< Number of samples per frame of input signal */
+ unsigned char *data, /**< Output payload (no more than max_data_bytes long) */
+ int max_data_bytes /**< Allocated memory for payload; don't use for controlling bitrate */
);
OPUS_EXPORT void opus_multistream_encoder_destroy(OpusMSEncoder *st);
@@ -77,43 +81,43 @@
OPUS_EXPORT int opus_multistream_encoder_ctl(OpusMSEncoder *st, int request, ...);
OPUS_EXPORT OpusMSDecoder *opus_multistream_decoder_create(
- int Fs, /* Sampling rate of input signal (Hz) */
- int channels, /* Number of channels (1/2) in input signal */
+ int Fs, /**< Sampling rate of input signal (Hz) */
+ int channels, /**< Number of channels (1/2) in input signal */
int streams,
int coupled_streams,
unsigned char *mapping,
- int *error /* Error code */
+ int *error /**< Error code */
);
OPUS_EXPORT int opus_multistream_decoder_init(
- OpusMSDecoder *st, /* Encoder state */
- int Fs, /* Sampling rate of input signal (Hz) */
- int channels, /* Number of channels (1/2) in input signal */
+ OpusMSDecoder *st, /**< Encoder state */
+ int Fs, /**< Sampling rate of input signal (Hz) */
+ int channels, /**< Number of channels (1/2) in input signal */
int streams,
int coupled_streams,
unsigned char *mapping
);
-/* Returns the number of samples decoded or a negative error code */
+/** Returns the number of samples decoded or a negative error code */
OPUS_EXPORT int opus_multistream_decode(
- OpusMSDecoder *st, /* Decoder state */
- const unsigned char *data, /* Input payload. Use a NULL pointer to indicate packet loss */
- int len, /* Number of bytes in payload */
- opus_int16 *pcm, /* Output signal (interleaved if 2 channels). length is frame_size*channels */
- int frame_size, /* Number of samples per frame of input signal */
- int decode_fec /* Flag (0/1) to request that any in-band forward error correction data be */
- /* decoded. If no such data is available the frame is decoded as if it were lost. */
+ OpusMSDecoder *st, /**< Decoder state */
+ const unsigned char *data, /**< Input payload. Use a NULL pointer to indicate packet loss */
+ int len, /**< Number of bytes in payload */
+ opus_int16 *pcm, /**< Output signal (interleaved if 2 channels). length is frame_size*channels */
+ int frame_size, /**< Number of samples per frame of input signal */
+ int decode_fec /**< Flag (0/1) to request that any in-band forward error correction data be */
+ /**< decoded. If no such data is available the frame is decoded as if it were lost. */
);
-/* Returns the number of samples decoded or a negative error code */
+/** Returns the number of samples decoded or a negative error code */
OPUS_EXPORT int opus_multistream_decode_float(
- OpusMSDecoder *st, /* Decoder state */
- const unsigned char *data, /* Input payload. Use a NULL pointer to indicate packet loss */
- int len, /* Number of bytes in payload */
- float *pcm, /* Output signal (interleaved if 2 channels). length is frame_size*channels */
- int frame_size, /* Number of samples per frame of input signal */
- int decode_fec /* Flag (0/1) to request that any in-band forward error correction data be */
- /* decoded. If no such data is available the frame is decoded as if it were lost. */
+ OpusMSDecoder *st, /**< Decoder state */
+ const unsigned char *data, /**< Input payload. Use a NULL pointer to indicate packet loss */
+ int len, /**< Number of bytes in payload */
+ float *pcm, /**< Output signal (interleaved if 2 channels). length is frame_size*channels */
+ int frame_size, /**< Number of samples per frame of input signal */
+ int decode_fec /**< Flag (0/1) to request that any in-band forward error correction data be */
+ /**< decoded. If no such data is available the frame is decoded as if it were lost. */
);
OPUS_EXPORT int opus_multistream_decoder_ctl(OpusMSDecoder *st, int request, ...);