From: Andre Noll <maan@tuebingen.mpg.de>
Date: Fri, 21 Jul 2017 17:45:31 +0000 (+0200)
Subject: Merge branch 'refs/heads/t/doxygen'
X-Git-Tag: v0.6.1~52
X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=6811b2f8ea8b7a8c77046285c9432aee6327da80

Merge branch 'refs/heads/t/doxygen'

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.
---

6811b2f8ea8b7a8c77046285c9432aee6327da80
diff --cc NEWS.md
index 313446f8,60b94238..5398d3a5
--- a/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
index b47def87,0d8d905c..1614c27c
--- a/afh_common.c
+++ b/afh_common.c
@@@ -16,8 -16,17 +16,18 @@@
  #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 aft.c
index 0c4c9328,d58f9daf..c2642ed3
--- a/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().
 + *
 + * 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().
-  *
-  * \sa get_chunk_table_of_row().
   */
  int get_afhi_of_row(const struct osl_row *row, struct afh_info *afhi)
  {
diff --cc mood.c
index 208bdc45,92bef0fa..315ef0cb
--- a/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)
  {