Documentation updates.
authorTimothy B. Terriberry <tterribe@xiph.org>
Mon, 1 Oct 2012 06:23:05 +0000 (23:23 -0700)
committerTimothy B. Terriberry <tterribe@xiph.org>
Mon, 1 Oct 2012 06:23:05 +0000 (23:23 -0700)
* Add Opus logo.
* Use @VERSION@ consistently.
* Fix some warnings/formatting exposed by a newer Doxygen versions.

Makefile.am
doc/Doxyfile.in
doc/opus_logo.svg [new file with mode: 0644]
include/opusfile.h

index 049d7e7..ef7f650 100644 (file)
@@ -27,11 +27,12 @@ debug:
 
 if HAVE_DOXYGEN
 
-EXTRA_DIST = doc/Doxyfile.in doc/git-version.sh
+EXTRA_DIST = doc/Doxyfile.in doc/opus_logo.svg
 
 all-local: doc/doxygen-build.stamp
 
-doc/doxygen-build.stamp: doc/Doxyfile $(top_srcdir)/include/*.h
+doc/doxygen-build.stamp: doc/Doxyfile $(top_srcdir)/doc/opus_logo.svg \
+ $(top_srcdir)/include/*.h
        cd doc && doxygen
        touch "$@"
 
index e34aa96..0cbc1e2 100644 (file)
@@ -6,7 +6,7 @@ PROJECT_BRIEF          = "Stand alone decoder library for .opus files."
 INPUT                  = @top_srcdir@/include/opusfile.h
 OPTIMIZE_OUTPUT_FOR_C  = YES
 
-FILE_VERSION_FILTER    = "/bin/sh @top_srcdir@/doc/git-version.sh"
+FILE_VERSION_FILTER    = "echo @VERSION@"
 
 QUIET                  = YES
 WARNINGS               = YES
@@ -16,3 +16,5 @@ WARN_NO_PARAMDOC       = YES
 
 JAVADOC_AUTOBRIEF      = YES
 SORT_MEMBER_DOCS       = NO
+
+PROJECT_LOGO           = @top_srcdir@/doc/opus_logo.svg
diff --git a/doc/opus_logo.svg b/doc/opus_logo.svg
new file mode 100644 (file)
index 0000000..794dd1d
--- /dev/null
@@ -0,0 +1,157 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   version="1.1"
+   x="0px"
+   y="0px"
+   width="97"
+   height="55"
+   viewBox="-72 -23.757 97 55"
+   overflow="visible"
+   enable-background="new -72 -23.757 169 78.757"
+   xml:space="preserve"
+   id="svg2"
+   style="overflow:visible">
+<defs
+   id="defs4">
+<linearGradient
+   xlink:href="#SVGID_1_"
+   id="linearGradient3027"
+   gradientUnits="userSpaceOnUse"
+   x1="194.53169"
+   y1="95.107399"
+   x2="194.53169"
+   y2="9.9475983e-14" /><linearGradient
+   xlink:href="#SVGID_2_"
+   id="linearGradient3029"
+   gradientUnits="userSpaceOnUse"
+   x1="229.61819"
+   y1="116.208"
+   x2="229.61819"
+   y2="164.46291" /><linearGradient
+   xlink:href="#SVGID_3_"
+   id="linearGradient3031"
+   gradientUnits="userSpaceOnUse"
+   x1="43.9897"
+   y1="115.4395"
+   x2="43.9897"
+   y2="165.2314" /><linearGradient
+   xlink:href="#SVGID_4_"
+   id="linearGradient3033"
+   gradientUnits="userSpaceOnUse"
+   x1="311.2847"
+   y1="115.7188"
+   x2="311.2847"
+   y2="165.2822" /><linearGradient
+   xlink:href="#SVGID_5_"
+   id="linearGradient3035"
+   gradientUnits="userSpaceOnUse"
+   x1="129.1987"
+   y1="115.5791"
+   x2="129.1987"
+   y2="204.4863" /></defs>
+<linearGradient
+   id="SVGID_1_"
+   gradientUnits="userSpaceOnUse"
+   x1="194.53169"
+   y1="95.107399"
+   x2="194.53169"
+   y2="9.9475983e-14">
+       <stop
+   offset="0.0056"
+   style="stop-color:#8E8E8E"
+   id="stop7" />
+       <stop
+   offset="1"
+   style="stop-color:#B5B5B5"
+   id="stop9" />
+</linearGradient>
+
+<linearGradient
+   id="SVGID_2_"
+   gradientUnits="userSpaceOnUse"
+   x1="229.61819"
+   y1="116.208"
+   x2="229.61819"
+   y2="164.46291">
+       <stop
+   offset="0.0056"
+   style="stop-color:#494748"
+   id="stop14" />
+       <stop
+   offset="1"
+   style="stop-color:#000000"
+   id="stop16" />
+</linearGradient>
+
+<linearGradient
+   id="SVGID_3_"
+   gradientUnits="userSpaceOnUse"
+   x1="43.9897"
+   y1="115.4395"
+   x2="43.9897"
+   y2="165.2314">
+       <stop
+   offset="0.0056"
+   style="stop-color:#494748"
+   id="stop21" />
+       <stop
+   offset="1"
+   style="stop-color:#000000"
+   id="stop23" />
+</linearGradient>
+
+<linearGradient
+   id="SVGID_4_"
+   gradientUnits="userSpaceOnUse"
+   x1="311.2847"
+   y1="115.7188"
+   x2="311.2847"
+   y2="165.2822">
+       <stop
+   offset="0.0056"
+   style="stop-color:#494748"
+   id="stop28" />
+       <stop
+   offset="1"
+   style="stop-color:#000000"
+   id="stop30" />
+</linearGradient>
+
+<linearGradient
+   id="SVGID_5_"
+   gradientUnits="userSpaceOnUse"
+   x1="129.1987"
+   y1="115.5791"
+   x2="129.1987"
+   y2="204.4863">
+       <stop
+   offset="0.0056"
+   style="stop-color:#494748"
+   id="stop35" />
+       <stop
+   offset="1"
+   style="stop-color:#000000"
+   id="stop37" />
+</linearGradient>
+<g
+   id="g3020"
+   transform="matrix(0.26931937,0,0,0.26931937,-72.00048,-23.756955)"><path
+     id="path11"
+     d="M 257.355,13.996 C 249.943,7.826 238.533,3.695 223.153,1.588 l -11.302,35.935 c -0.244,1.318 -0.664,2.815 -1.315,4.54 -1.153,2.883 -2.542,5.258 -4.174,7.127 -1.634,1.874 -3.463,3.335 -5.489,4.4 -2.028,1.059 -4.232,1.79 -6.614,2.193 -2.382,0.4 -4.847,0.526 -7.393,0.378 -2.549,-0.148 -4.717,-0.495 -6.501,-1.042 -1.786,-0.546 -3.428,-1.452 -4.925,-2.72 -1.107,-1.245 -1.751,-2.878 -1.927,-4.902 -0.177,-2.024 0.313,-4.527 1.471,-7.509 1.035,-2.592 2.345,-4.852 3.933,-6.771 1.587,-1.921 3.443,-3.411 5.565,-4.467 2.027,-1.059 4.206,-1.768 6.539,-2.125 2.327,-0.354 4.915,-0.448 7.756,-0.283 2.352,0.139 4.542,0.485 6.574,1.048 0.964,0.265 1.808,0.613 2.542,1.033 L 216.57,0.832 c -2.142,-0.202 -4.333,-0.379 -6.609,-0.51 -21.901,-1.279 -40.308,1.251 -55.229,7.576 -14.918,6.33 -24.865,15.715 -29.833,28.154 -1.491,3.814 -2.292,7.408 -2.41,10.785 l -0.01,-0.005 c -1.426,24.463 14.295,38.245 24.007,44.373 3.897,2.609 7.362,3.901 7.362,3.901 l 4.451,-14.225 1.316,-3.496 c 5.859,1.108 12.375,1.879 19.573,2.298 22.053,1.286 40.539,-1.232 55.458,-7.564 14.916,-6.325 24.78,-15.638 29.591,-27.942 4.806,-12.295 2.514,-22.357 -6.882,-30.181 z"
+     style="fill:url(#linearGradient3027)"/><path
+     id="path18"
+     d="m 269.531,139.499 c -2.511,7.718 -8.23,13.807 -17.156,18.27 -8.926,4.463 -20.223,6.694 -33.891,6.694 -13.484,0 -23.292,-2.208 -29.43,-6.626 -6.136,-4.415 -7.904,-10.528 -5.299,-18.338 l 7.53,-23.291 h 25.663 l -7.252,23.151 c -0.931,2.883 -1.232,5.278 -0.906,7.183 0.326,1.907 1.046,3.417 2.162,4.533 1.394,1.113 2.95,1.88 4.672,2.299 1.72,0.419 3.788,0.629 6.207,0.629 2.417,0 4.742,-0.255 6.974,-0.769 2.231,-0.51 4.275,-1.323 6.138,-2.438 1.858,-1.116 3.508,-2.602 4.951,-4.463 1.44,-1.859 2.626,-4.186 3.557,-6.974 l 7.532,-23.151 h 25.663 l -7.115,23.291 z"
+     style="fill:url(#linearGradient3029)"/><path
+     id="path25"
+     d="m 86.875,140.404 c 2.51,-7.717 0.743,-13.808 -5.301,-18.271 -6.044,-4.463 -15.899,-6.694 -29.567,-6.694 -13.483,0 -24.686,2.21 -33.611,6.625 -8.928,4.417 -14.693,10.53 -17.295,18.34 -2.51,7.72 -0.722,13.786 5.37,18.201 6.089,4.418 15.922,6.626 29.498,6.626 13.575,0 24.826,-2.208 33.753,-6.626 8.924,-4.415 14.642,-10.481 17.153,-18.201 z m -26.082,0.14 c -0.931,2.978 -2.069,5.3 -3.417,6.974 -1.349,1.675 -3.046,3.116 -5.09,4.323 -1.768,1.116 -3.765,1.883 -5.997,2.302 -2.232,0.419 -4.463,0.627 -6.696,0.627 -2.697,0 -4.999,-0.23 -6.903,-0.696 -1.907,-0.465 -3.417,-1.256 -4.533,-2.371 -1.21,-1.116 -1.906,-2.626 -2.092,-4.533 -0.188,-1.904 0.14,-4.114 0.977,-6.625 0.929,-2.88 2.161,-5.275 3.696,-7.183 1.534,-1.904 3.229,-3.417 5.09,-4.533 2.138,-1.115 4.206,-1.882 6.207,-2.301 1.999,-0.419 4.207,-0.627 6.625,-0.627 2.416,0 4.603,0.257 6.555,0.767 1.953,0.512 3.486,1.325 4.603,2.44 1.115,1.116 1.789,2.605 2.021,4.463 0.231,1.86 -0.117,4.185 -1.046,6.973 z"
+     style="fill:url(#linearGradient3031)"/><path
+     id="path32"
+     d="m 310.14,126.807 c 2.928,-0.698 9.041,-1.046 18.339,-1.046 4.833,0 9.506,0.487 14.018,1.465 4.508,0.976 9.042,2.209 13.598,3.696 L 360,119.066 c -2.698,-0.744 -6.625,-1.487 -11.787,-2.231 -5.159,-0.744 -10.669,-1.116 -16.526,-1.116 -17.574,0 -30.405,1.513 -38.493,4.533 -8.089,3.022 -12.879,6.812 -14.366,11.366 -1.115,3.44 -0.348,6.346 2.302,8.717 2.65,2.371 7.322,4.115 14.016,5.229 2.511,0.467 6.624,0.838 12.343,1.117 5.718,0.279 9.46,0.557 11.228,0.836 3.717,0.373 6.205,0.837 7.461,1.396 1.254,0.558 1.695,1.394 1.325,2.511 -0.467,1.303 -1.976,2.279 -4.533,2.928 -2.559,0.652 -6.3,0.977 -11.227,0.977 -0.77,0 -1.513,-0.003 -2.241,-0.007 -1.846,-0.101 -3.858,-0.272 -5.791,-0.476 -2.06,-0.22 -4.118,-0.485 -6.162,-0.795 -4.089,-0.62 -8.132,-1.419 -12.058,-2.439 -3.921,-1.022 -7.734,-2.267 -11.26,-3.813 -0.474,-0.208 -0.932,-0.433 -1.394,-0.654 -2.476,3.979 -5.905,7.451 -10.27,10.396 2.259,1.085 4.539,1.976 6.807,2.742 4.52,1.506 9.034,2.52 13.525,3.266 4.494,0.741 8.969,1.203 13.431,1.472 2.231,0.133 4.459,0.215 6.691,0.248 1.966,0.026 3.882,0.02 5.902,-0.045 12.216,-0.072 22.318,-1.53 30.294,-4.386 8.18,-2.929 13.062,-6.81 14.644,-11.645 1.116,-3.349 0.441,-6.138 -2.021,-8.369 -2.466,-2.231 -6.813,-3.857 -13.041,-4.882 -2.883,-0.371 -5.768,-0.719 -8.647,-1.046 -2.884,-0.324 -5.533,-0.628 -7.951,-0.906 -9.577,-0.65 -14.924,-1.255 -16.039,-1.813 -1.116,-0.558 -1.488,-1.394 -1.116,-2.511 0.467,-1.209 2.164,-2.163 5.094,-2.859 z"
+     style="fill:url(#linearGradient3033)"/><path
+     id="path39"
+     d="m 172.838,122.204 c -6.091,-4.415 -15.924,-6.625 -29.499,-6.625 -13.577,0 -24.826,2.21 -33.751,6.625 -8.926,4.417 -14.4,10.415 -16.911,18.131 l -0.105,0.349 -12.692,39.19 c -5.26,17.631 17.526,24.612 17.526,24.612 l 7.58,-24.612 0.656,-2.106 c 0.592,-1.982 1.192,-3.964 1.781,-5.948 l 1.686,-5.531 c 0.603,-1.832 1.207,-3.662 1.85,-5.481 l 3.979,-10.875 1.993,-5.436 1.429,-3.718 c 0.051,-0.172 0.099,-0.339 0.155,-0.514 0.836,-2.509 1.953,-4.718 3.347,-6.624 1.396,-1.904 3.069,-3.417 5.021,-4.533 1.859,-1.115 3.882,-1.904 6.067,-2.371 2.183,-0.464 4.625,-0.696 7.322,-0.696 2.231,0 4.325,0.208 6.277,0.627 1.952,0.419 3.438,1.186 4.463,2.301 1.301,1.209 2.068,2.65 2.3,4.323 0.231,1.675 -0.117,3.999 -1.046,6.974 -0.931,2.79 -2.116,5.116 -3.557,6.974 -1.442,1.862 -3.091,3.348 -4.951,4.464 -1.861,1.115 -3.905,1.931 -6.136,2.44 -2.231,0.512 -4.558,0.767 -6.973,0.767 -2.419,0 -4.487,-0.208 -6.207,-0.627 -1.721,-0.419 -3.326,-1.186 -4.812,-2.302 -0.112,-0.112 -0.201,-0.247 -0.305,-0.366 l -3.674,10.658 c -0.206,0.613 -0.403,1.228 -0.601,1.842 3.479,0.708 7.507,1.13 12.111,1.256 13.668,0 24.965,-2.231 33.893,-6.694 8.926,-4.464 14.643,-10.552 17.154,-18.271 2.511,-7.719 0.718,-13.786 -5.37,-18.203 z"
+     style="fill:url(#linearGradient3035)"/></g>
+</svg>
index 12fdb62..95ceeca 100644 (file)
@@ -339,7 +339,7 @@ void opus_tags_init(OpusTags *_tags) OP_ARG_NONNULL(1);
                   the tag to add (without an '=' character).
    \param _value A NUL-terminated UTF-8 containing the corresponding value.
    \return 0 on success, or a negative value on failure.
-   \retval OP_EFAULT An internal memory allocation failed.*/
+   \retval #OP_EFAULT An internal memory allocation failed.*/
 int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2) OP_ARG_NONNULL(3);
 
@@ -352,7 +352,7 @@ int opus_tags_add(OpusTags *_tags,const char *_tag,const char *_value)
    \param _comment A NUL-terminated UTF-8 string containing the comment in
                     "TAG=value" form.
    \return 0 on success, or a negative value on failure.
-   \retval OP_EFAULT An internal memory allocation failed.*/
+   \retval #OP_EFAULT An internal memory allocation failed.*/
 int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
 
@@ -370,7 +370,7 @@ int opus_tags_add_comment(OpusTags *_tags,const char *_comment)
            This points directly to data in the #OpusTags structure.
            It should not be modified or freed by the application, and
             modifications to the structure may invalidate the pointer.
-   \retval <code>NULL</code> if no matching tag is found.*/
+   \retval NULL If no matching tag is found.*/
 const char *opus_tags_query(const OpusTags *_tags,const char *_tag,int _count)
  OP_ARG_NONNULL(1) OP_ARG_NONNULL(2);
 
@@ -463,9 +463,9 @@ typedef int (*op_close_func)(void *_stream);
     <code>fclose()</code>.
    The differences are that the <code>FILE *</code> arguments have been
     replaced with a <code>void *</code>, which is to be used as a pointer to
-    whatever internal data these functions might need, that #seek_func and
-    #tell_func take and return 64-bit offsets, and that #seek_func *must*
-    return -1 if the stream is unseekable.*/
+    whatever internal data these functions might need, that #seek and #tell
+    take and return 64-bit offsets, and that #seek <em>must</em> return -1 if
+    the stream is unseekable.*/
 struct OpusFileCallbacks{
   /**Used to read data from the stream.
      This must not be <code>NULL</code>.*/
@@ -657,7 +657,7 @@ int op_test(OpusHead *_head,
                       The failure code will be #OP_EFAULT if the file could not
                        be opened, or one of the other failure codes from
                        op_open_callbacks() otherwise.
-   \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+   \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error)
  OP_ARG_NONNULL(1);
 
@@ -668,7 +668,7 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_file(const char *_path,int *_error)
                       You may pass in <code>NULL</code> if you don't want the
                        failure code.
                       See op_open_callbacks() for a full list of failure codes.
-   \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+   \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data,
  size_t _size,int *_error);
 
@@ -683,7 +683,7 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_memory(const unsigned char *_data,
                       You may pass in <code>NULL</code> if you don't want the
                        failure code.
                       See op_open_callbacks() for a full list of failure codes.
-   \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+   \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
  int _flags,int *_error) OP_ARG_NONNULL(1);
 
@@ -717,7 +717,7 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
                             the failure code.
                            See op_open_callbacks() for a full list of failure
                             codes.
-   \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+   \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url_with_proxy(const char *_url,
  int _flags,const char *_proxy_host,unsigned _proxy_port,
  const char *_proxy_user,const char *_proxy_pass,int *_error)
@@ -738,7 +738,7 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url_with_proxy(const char *_url,
                           also.
                          <code><a href="#op_close_func">close()</a></code> may
                           be <code>NULL</code>, but if it is not, it will be
-                          called when the #OggOpusFile is destroyed by
+                          called when the \c OggOpusFile is destroyed by
                           op_free().
                          It will not be called if op_open_callbacks() fails
                           with an error.
@@ -795,7 +795,7 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url_with_proxy(const char *_url,
                            <dd>The first or last timestamp in a link failed
                             basic validity checks.</dd>
                          </dl>
-   \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+   \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.*/
 OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_source,
  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
@@ -809,7 +809,7 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_source,
                       The failure code will be #OP_EFAULT if the file could not
                        be opened, or one of the other failure codes from
                        op_open_callbacks() otherwise.
-   \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
+   \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error)
  OP_ARG_NONNULL(1);
 
@@ -821,7 +821,7 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_file(const char *_path,int *_error)
                       You may pass in <code>NULL</code> if you don't want the
                        failure code.
                       See op_open_callbacks() for a full list of failure codes.
-   \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
+   \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data,
  size_t _size,int *_error);
 
@@ -837,7 +837,7 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_memory(const unsigned char *_data,
                       You may pass in <code>NULL</code> if you don't want the
                        failure code.
                       See op_open_callbacks() for a full list of failure codes.
-   \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
+   \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,int _flags,
  int *_error) OP_ARG_NONNULL(1);
 
@@ -872,7 +872,7 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,int _flags,
                             the failure code.
                            See op_open_callbacks() for a full list of failure
                             codes.
-   \return An #OggOpusFile pointer on success, or <code>NULL</code> on error.*/
+   \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url_with_proxy(const char *_url,
  int _flags,const char *_proxy_host,unsigned _proxy_port,
  const char *_proxy_user,const char *_proxy_pass,int *_error)
@@ -897,7 +897,7 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url_with_proxy(const char *_url,
                           also.
                          <code><a href="#op_close_func">close()</a></code> may
                           be <code>NULL</code>, but if it is not, it will be
-                          called when the #OggOpusFile is destroyed by
+                          called when the \c OggOpusFile is destroyed by
                           op_free().
                          It will not be called if op_open_callbacks() fails
                           with an error.
@@ -921,7 +921,7 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url_with_proxy(const char *_url,
                           the failure code.
                          See op_open_callbacks() for a full list of failure
                           codes.
-   \return A freshly opened #OggOpusFile, or <code>NULL</code> on error.*/
+   \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.*/
 OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_source,
  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
@@ -929,8 +929,8 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_source,
 /**Finish opening a stream partially opened with op_test_callbacks() or one of
     the associated convenience functions.
    If this function fails, you are still responsible for freeing the
-    #OggOpusFile with op_free().
-   \param _of The #OggOpusFile to finish opening.
+    \c OggOpusFile with op_free().
+   \param _of The \c OggOpusFile to finish opening.
    \return 0 on success, or a negative value on error.
    \retval #OP_EREAD         An underlying read, seek, or tell operation failed
                               when it should have succeeded.
@@ -954,8 +954,8 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_source,
                               validity checks.*/
 int op_test_open(OggOpusFile *_of) OP_ARG_NONNULL(1);
 
-/**Release all memory used by an #OggOpusFile.
-   \param _of The #OggOpusFile to free.*/
+/**Release all memory used by an \c OggOpusFile.
+   \param _of The \c OggOpusFile to free.*/
 void op_free(OggOpusFile *_of);
 
 /*@}*/
@@ -983,7 +983,7 @@ void op_free(OggOpusFile *_of);
    This function may be called on partially-opened streams, but it will always
     return 1.
    The actual number of links is not known until the stream is fully opened.
-   \param _of The #OggOpusFile from which to retrieve the link count.
+   \param _of The \c OggOpusFile from which to retrieve the link count.
    \return For seekable sources, this returns the total number of links in the
             whole stream.
            For unseekable sources, this always returns 1.*/
@@ -1001,7 +1001,7 @@ int op_link_count(OggOpusFile *_of) OP_ARG_NONNULL(1);
     successfully able to report the position indicator afterwards.</li>
    </ol>
    This function may be called on partially-opened streams.
-   \param _of The #OggOpusFile whose seekable status is to be returned.
+   \param _of The \c OggOpusFile whose seekable status is to be returned.
    \return A non-zero value if seekable, and 0 if unseekable.*/
 int op_seekable(OggOpusFile *_of) OP_ARG_NONNULL(1);
 
@@ -1009,7 +1009,7 @@ int op_seekable(OggOpusFile *_of) OP_ARG_NONNULL(1);
     stream.
    This function may be called on partially-opened streams, but it will always
     return the serial number of the Opus stream in the first link.
-   \param _of The #OggOpusFile from which to retrieve the serial number.
+   \param _of The \c OggOpusFile from which to retrieve the serial number.
    \param _li The index of the link whose serial number should be retrieved.
               Use a negative number to get the serial number of the current
                link.
@@ -1026,7 +1026,7 @@ opus_uint32 op_serialno(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
     is provided for convenience.
    This function may be called on partially-opened streams, but it will always
     return the serial number of the Opus stream in the first link.
-   \param _of The #OggOpusFile from which to retrieve the channel count.
+   \param _of The \c OggOpusFile from which to retrieve the channel count.
    \param _li The index of the link whose channel count should be retrieved.
               Use a negative number to get the channel count of the current
                link.
@@ -1040,7 +1040,7 @@ int op_channel_count(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
 /**Get the total (compressed) size of the stream, or of an individual link in
     a (possibly-chained) Ogg Opus stream, including all headers and Ogg muxing
     overhead.
-   \param _of The #OggOpusFile from which to retrieve the compressed size.
+   \param _of The \c OggOpusFile from which to retrieve the compressed size.
    \param _li The index of the link whose compressed size should be computed.
               Use a negative number to get the compressed size of the entire
                stream.
@@ -1062,7 +1062,7 @@ opus_int64 op_raw_total(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
    Because timestamps in Opus are fixed at 48 kHz, there is no need for a
     separate function to convert this to seconds (and leaving it out avoids
     introducing floating point to the API, for those that wish to avoid it).
-   \param _of The #OggOpusFile from which to retrieve the PCM offset.
+   \param _of The \c OggOpusFile from which to retrieve the PCM offset.
    \param _li The index of the link whose PCM length should be computed.
               Use a negative number to get the PCM length of the entire stream.
    \return The PCM length of the entire stream if \a _li is negative, the PCM
@@ -1077,7 +1077,7 @@ ogg_int64_t op_pcm_total(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
     Opus stream.
    This function may be called on partially-opened streams, but it will always
     return the ID header information of the Opus stream in the first link.
-   \param _of The #OggOpusFile from which to retrieve the ID header
+   \param _of The \c OggOpusFile from which to retrieve the ID header
                information.
    \param _li The index of the link whose ID header information should be
                retrieved.
@@ -1091,7 +1091,7 @@ const OpusHead *op_head(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
 
 /**Get the comment header information for the given link in a (possibly
     chained) Ogg Opus stream.
-   \param _of The #OggOpusFile from which to retrieve the comment header
+   \param _of The \c OggOpusFile from which to retrieve the comment header
                information.
    \param _li The index of the link whose comment header information should be
                retrieved.
@@ -1111,7 +1111,7 @@ const OpusTags *op_tags(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
     that the seek target landed in.
    Reading more data may advance the link index (even on the first read after a
     seek).
-   \param _of The #OggOpusFile from which to retrieve the current link index.
+   \param _of The \c OggOpusFile from which to retrieve the current link index.
    \return The index of the current link on success, or a negative value on
             failture.
            For seekable streams, this is a number between 0 and the value
@@ -1126,7 +1126,7 @@ int op_current_link(OggOpusFile *_of) OP_ARG_NONNULL(1);
     stream.
    The stream must be seekable to compute the bitrate.
    For unseekable streams, use op_bitrate_instant() to get periodic estimates.
-   \param _of The #OggOpusFile from which to retrieve the bitrate.
+   \param _of The \c OggOpusFile from which to retrieve the bitrate.
    \param _li The index of the link whose bitrate should be computed.
               USe a negative number to get the bitrate of the whole stream.
    \return The bitrate on success, or a negative value on error.
@@ -1141,15 +1141,15 @@ opus_int32 op_bitrate(OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
    This will spike somewhat after a seek or at the start/end of a chain
     boundary, as pre-skip, pre-roll, and end-trimming causes samples to be
     decoded but not played.
-   \param _of The #OggOpusFile from which to retrieve the bitrate.
+   \param _of The \c OggOpusFile from which to retrieve the bitrate.
    \return The bitrate, in bits per second, or a negative value on error.
-   \retval #OP_EFALSE No data has been decoded since any of the events
+   \retval #OP_FALSE  No data has been decoded since any of the events
                        described above.
    \retval #OP_EINVAL The stream was not fully open.*/
 opus_int32 op_bitrate_instant(OggOpusFile *_of) OP_ARG_NONNULL(1);
 
 /**Obtain the current value of the position indicator for \a _of.
-   \param _of The #OggOpusFile from which to retrieve the position indicator.
+   \param _of The \c OggOpusFile from which to retrieve the position indicator.
    \return The byte position that is currently being read from.
    \retval #OP_EINVAL The stream was not fully open.*/
 opus_int64 op_raw_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
@@ -1158,7 +1158,7 @@ opus_int64 op_raw_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
    If the stream is not properly timestamped, this might not increment by the
     proper amount between reads, or even return monotonically increasing
     values.
-   \param _of The #OggOpusFile from which to retrieve the PCM offset.
+   \param _of The \c OggOpusFile from which to retrieve the PCM offset.
    \return The PCM offset of the next sample to be read.
    \retval #OP_EINVAL The stream was not fully open.*/
 ogg_int64_t op_pcm_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
@@ -1198,7 +1198,7 @@ ogg_int64_t op_pcm_tell(OggOpusFile *_of) OP_ARG_NONNULL(1);
    This also scans packets to update the PCM cursor.
    It will cross a logical bitstream boundary, but only if it can't get any
     packets out of the tail of the link to which it seeks.
-   \param _of          The #OggOpusFile in which to seek.
+   \param _of          The \c OggOpusFile in which to seek.
    \param _byte_offset The byte position to seek to.
    \return 0 on success, or a negative error code on failure.
    \retval #OP_EREAD    The seek failed.
@@ -1213,7 +1213,7 @@ int op_raw_seek(OggOpusFile *_of,opus_int64 _byte_offset) OP_ARG_NONNULL(1);
     quickly arrive at the requested position.
    This is faster than sample-granularity seeking because it doesn't do the
     last bit of decode to find a specific sample.
-   \param _of         The #OggOpusFile in which to seek.
+   \param _of         The \c OggOpusFile in which to seek.
    \param _pcm_offset The PCM offset to seek to.
                       This is in samples at 48 kHz relative to the start of the
                        stream.
@@ -1227,7 +1227,7 @@ int op_pcm_seek_page(OggOpusFile *_of,ogg_int64_t _pcm_offset)
 
 /**Seek to the specified PCM offset, such that decoding will begin at exactly
     the requested position.
-   \param _of         The #OggOpusFile in which to seek.
+   \param _of         The \c OggOpusFile in which to seek.
    \param _pcm_offset The PCM offset to seek to.
                       This is in samples at 48 kHz relative to the start of the
                        stream.
@@ -1292,7 +1292,7 @@ int op_pcm_seek(OggOpusFile *_of,ogg_int64_t _pcm_offset) OP_ARG_NONNULL(1);
         they will simply read too few (rather than reading too many and going
         off the end of the buffer).</li>
    </ol>
-   \param      _of       The #OggOpusFile from which to read.
+   \param      _of       The \c OggOpusFile from which to read.
    \param[out] _pcm      A buffer in which to store the output PCM samples, as
                           signed native-endian 16-bit values with a nominal
                           range of <code>[-32768,32767)</code>.
@@ -1365,7 +1365,7 @@ OP_WARN_UNUSED_RESULT int op_read(OggOpusFile *_of,
         they will simply read too few (rather than reading too many and going
         off the end of the buffer).</li>
    </ol>
-   \param      _of       The #OggOpusFile from which to read.
+   \param      _of       The \c OggOpusFile from which to read.
    \param[out] _pcm      A buffer in which to store the output PCM samples as
                           signed floats with a nominal range of
                           <code>[-1.0,1.0]</code>.
@@ -1426,7 +1426,7 @@ OP_WARN_UNUSED_RESULT int op_read_float(OggOpusFile *_of,
     in \a _pcm, while the return value is the number of samples <em>per
     channel</em>, even though the channel count is known, for consistency with
     op_read().
-   \param      _of       The #OggOpusFile from which to read.
+   \param      _of       The \c OggOpusFile from which to read.
    \param[out] _pcm      A buffer in which to store the output PCM samples, as
                           signed native-endian 16-bit values with a nominal
                           range of <code>[-32768,32767)</code>.
@@ -1479,7 +1479,7 @@ OP_WARN_UNUSED_RESULT int op_read_stereo(OggOpusFile *_of,
     in \a _pcm, while the return value is the number of samples <em>per
     channel</em>, even though the channel count is known, for consistency with
     op_read_float().
-   \param      _of       The #OggOpusFile from which to read.
+   \param      _of       The \c OggOpusFile from which to read.
    \param[out] _pcm      A buffer in which to store the output PCM samples, as
                           signed floats with a nominal range of
                           <code>[-1.0,1.0]</code>.