Merge branch 'refs/heads/t/doxygen'
authorAndre Noll <maan@tuebingen.mpg.de>
Fri, 21 Jul 2017 17:45:31 +0000 (19:45 +0200)
committerAndre Noll <maan@tuebingen.mpg.de>
Fri, 21 Jul 2017 17:51:17 +0000 (19:51 +0200)
This series contains an update of Doxyfile to a newer doxygen version
and an overhaul of the source code documentation. Several stale
references have been fixed. Other parts of the documentation have
been improved.

Cooking for almost a month.

* refs/heads/t/doxygen:
  aft.c: Trivial spelling/whitespace fixes.
  afh: Expand documentation of init function declarations.
  filter: Remove duplicate documentation of filter_get().
  doxygen: Improve documentation of struct receiver.
  doxygen: Add \ref to references.
  Improve documentation of mm.c and mm.h.
  doxygen: Don't refer to Black Hats Manual.
  doxygen: Don't refer to libosl functions.
  doxygen: Trivial cleanups.
  doxygen: Remove some stale doxygen references.
  recv: Explain user data mechanism.
  Update to doxygen-1.8.11.

The merge resulted in a few conflicts which were easy to resolve.

1  2 
NEWS.md
afh_common.c
afs.h
aft.c
error.h
mood.c
play.c
string.c

diff --cc NEWS.md
+++ b/NEWS.md
@@@ -1,13 -1,6 +1,16 @@@
  NEWS
  ====
  
 +------------------------------------------------
 +0.6.1 (to be announced) "hyperbolic correlation"
 +------------------------------------------------
 +
 +- The contents of overview.pdf have been integrated into the user
 +  manual.
++- The doxygen source browser has been disabled temporarily. The
++  API reference is still online, though.
++- Overhaul of the source code documentation.
 +
  -------------------------------
  0.6.0 (2017-04-28) "fuzzy flux"
  -------------------------------
diff --cc afh_common.c
  #include "afh.h"
  
  typedef void afh_init_func(struct audio_format_handler *);
- /* It does not hurt to declare init functions which are not available. */
++
+ /*
+  * Declaration of the audio format handler init functions.
+  *
+  * These symbols are referenced in the afl array below.
+  *
+  * Most audio format handlers depend on an external library and are not
+  * compiled in if the library is not installed. Hence it is well possible that
+  * not all of these functions are defined. It does not hurt to declare them
+  * anyway, and this avoids another set of ifdefs.
+  */
 -extern afh_init_func mp3_init, ogg_init, aac_afh_init, wma_afh_init,
 +extern afh_init_func mp3_afh_init, ogg_afh_init, aac_afh_init, wma_afh_init,
        spx_afh_init, flac_afh_init, opus_afh_init;
  
  /** The list of all status items */
diff --cc afs.h
Simple merge
diff --cc aft.c
--- 1/aft.c
--- 2/aft.c
+++ b/aft.c
@@@ -590,12 -592,6 +593,10 @@@ static int get_hash_of_row(const struc
   * \param afhi Result pointer.
   *
   * \return The return value of the underlying call to osl_get_object().
-  *
-  * \sa get_chunk_table_of_row().
 + *
 + * After the call the members of the afhi structure point to mapped memory
 + * which is owned by the osl table, Hence the caller must not attempt to free
 + * this memory by calling \ref clear_afhi().
   */
  int get_afhi_of_row(const struct osl_row *row, struct afh_info *afhi)
  {
diff --cc error.h
Simple merge
diff --cc mood.c
--- 1/mood.c
--- 2/mood.c
+++ b/mood.c
@@@ -854,19 -846,14 +846,15 @@@ out
        free(aa.array);
        return ret;
  }
- /**
 +
+ /*
   * Close and re-open the current mood.
   *
-  * This function is used if changes to the audio file table or the
-  * attribute table were made that render the current list of admissible
-  * files useless. For example, if an attribute is removed from the
-  * attribute table, this function is called.
-  *
-  * \return Positive on success, negative on errors. If no mood is currently
-  * open, the function returns success.
+  * This function is called on events which render the current list of
+  * admissible files useless, for example if an attribute is removed from the
+  * attribute table.
   *
-  * \sa mood_open(), mood_close().
+  * If no mood is currently open, the function returns success.
   */
  static int reload_current_mood(void)
  {
diff --cc play.c
Simple merge
diff --cc string.c
Simple merge