Add initial Doxygen support for generating api documentation.

Doxygen is a tool for generating programming documentation
based on comments in header and source files. This commit
adds the necessary configuration file and associated support
in the autotools build.

Right now it doesn't generate much documentation because our
public header files aren't marked up. Warnings are printed
for undocumented members and arguments.

Makefile.am

@@ -2,7 +2,7 @@ AUTOMAKE_OPTIONS = subdir-objects
 
 lib_LTLIBRARIES = libopus.la
 
-SUBDIRS = . libcelt/tests
+SUBDIRS = . libcelt/tests doc
 
 INCLUDES = -I$(top_srcdir)/libcelt -I$(top_srcdir)/silk -I$(top_srcdir)/silk/float -I$(top_srcdir)/silk/fixed
 

configure.ac

@@ -148,6 +148,17 @@ AC_ARG_ENABLE(fuzzing, [  --enable-fuzzing     causes the encoder to make random
   AC_DEFINE([FUZZING], , [Fuzzing])
 fi])
 
+ac_enable_doc="yes"
+AC_ARG_ENABLE([doc],
+  AS_HELP_STRING([--disable-doc], [Do not build API documentation]),
+                 [ac_enable_doc=$enableval])
+AC_CHECK_PROG(HAVE_DOXYGEN, [doxygen], [yes], [no])
+if test "$HAVE_DOXYGEN" != "yes" -o "$ac_enable_doc" != "yes"; then
+  HAVE_DOXYGEN="false"
+  ac_enable_doc="no"
+fi
+AM_CONDITIONAL(HAVE_DOXYGEN, [test $HAVE_DOXYGEN = yes])
+
 if test "$OPUS_BUILD" != "true" ; then
 saved_CFLAGS="$CFLAGS"
 CFLAGS="$CFLAGS -fvisibility=hidden"
@@ -209,7 +220,8 @@ AM_CONDITIONAL([FIXED_POINT], [test x$ac_enable_fixed = xyes])
 AM_CONDITIONAL([CUSTOM_MODES], [test x$ac_enable_custom_modes = xyes])
 
 AC_OUTPUT([Makefile libcelt/tests/Makefile
-           opus.pc opus-uninstalled.pc])
+           opus.pc opus-uninstalled.pc
+           doc/Makefile doc/Doxyfile])
 
 AC_MSG_RESULT([
 ------------------------------------------------------------------------
@@ -229,6 +241,8 @@ AC_MSG_RESULT([
       Custom modes: .................. ${ac_enable_custom_modes}
       Assertion checking: ............ ${ac_enable_assertions}
       Fuzzing: ..           .......... ${ac_enable_fuzzing}
+
+      API documentation: ............. ${ac_enable_doc}
 ------------------------------------------------------------------------
 ])
 

doc/Makefile.am

@@ -0,0 +1,20 @@
+## Process this file with automake to produce Makefile.in
+
+DOCINPUTS = $(top_srcdir)/src/opus.h \
+            $(top_srcdir)/src/opus_multistream.h \
+            $(top_srcdir)/libcelt/opus_defines.h \
+            $(top_srcdir)/libcelt/opus_types.h
+
+doc_DATA = doxygen-build.stamp
+
+EXTRA_DIST = Doxyfile.in
+
+if HAVE_DOXYGEN
+doxygen-build.stamp: Doxyfile $(DOCINPUTS)
+	doxygen
+	touch $@
+else
+doxygen-build.stamp: Doxyfile $(DOCINPUTS)
+	@echo "*** Warning: Doxygen not found; API documentation will not be built."
+	touch $@
+endif