From b23f7bcde58fdada9170f16af39ab1e84f4c3a68 Mon Sep 17 00:00:00 2001
From: Gabor X Toth <*@tg-x.net>
Date: Mon, 11 Jan 2016 21:23:17 +0000
Subject: [PATCH] doxygen: group/module definitions (part 1)

---
 src/include/block_dns.h                       |   4 +-
 src/include/block_fs.h                        |   5 +-
 src/include/block_regex.h                     |   5 +-
 src/include/gauger.h                          |   2 +-
 src/include/gnunet_applications.h             |   5 +-
 src/include/gnunet_arm_service.h              |  10 +-
 src/include/gnunet_ats_plugin.h               |  22 ++-
 src/include/gnunet_ats_service.h              |  11 +-
 src/include/gnunet_bandwidth_lib.h            |  11 +-
 src/include/gnunet_bio_lib.h                  |   9 +-
 src/include/gnunet_block_lib.h                |  11 +-
 src/include/gnunet_block_plugin.h             |  14 +-
 src/include/gnunet_cadet_service.h            |  16 +-
 src/include/gnunet_client_lib.h               |   9 +-
 src/include/gnunet_client_manager_lib.h       |  16 +-
 src/include/gnunet_configuration_lib.h        |   9 +-
 src/include/gnunet_connection_lib.h           |  12 +-
 src/include/gnunet_consensus_service.h        |  10 +-
 src/include/gnunet_constants.h                |   5 +-
 src/include/gnunet_container_lib.h            |  24 ++-
 src/include/gnunet_conversation_service.h     |  10 +-
 src/include/gnunet_core_service.h             |  10 +-
 src/include/gnunet_crypto_lib.h               |   6 +-
 src/include/gnunet_datacache_lib.h            |  19 +-
 src/include/gnunet_datacache_plugin.h         |  10 +-
 src/include/gnunet_datastore_plugin.h         |  56 +++---
 src/include/gnunet_datastore_service.h        |  21 +-
 src/include/gnunet_dht_service.h              |  13 +-
 src/include/gnunet_disk_lib.h                 |  10 +-
 src/include/gnunet_dns_service.h              |  12 +-
 src/include/gnunet_dnsparser_lib.h            |  10 +-
 src/include/gnunet_dnsstub_lib.h              |  11 +-
 src/include/gnunet_dv_service.h               |  12 +-
 src/include/gnunet_env_lib.h                  |  16 +-
 src/include/gnunet_fragmentation_lib.h        |  13 +-
 src/include/gnunet_friends_lib.h              |  12 +-
 src/include/gnunet_fs_service.h               |  12 +-
 src/include/gnunet_getopt_lib.h               |   9 +-
 src/include/gnunet_gns_service.h              |  12 +-
 src/include/gnunet_gnsrecord_lib.h            |  11 +-
 src/include/gnunet_gnsrecord_plugin.h         |  15 +-
 src/include/gnunet_hello_lib.h                |  10 +-
 src/include/gnunet_helper_lib.h               |  16 +-
 .../gnunet_identity_provider_service.h        |  13 +-
 src/include/gnunet_identity_service.h         |   9 +-
 src/include/gnunet_load_lib.h                 |  10 +-
 src/include/gnunet_microphone_lib.h           |  10 +-
 src/include/gnunet_mq_lib.h                   |   9 +-
 src/include/gnunet_multicast_service.h        |  12 +-
 src/include/gnunet_mysql_lib.h                |  10 +-
 src/include/gnunet_nse_service.h              |  11 +-
 src/include/gnunet_os_lib.h                   |   5 +-
 src/include/gnunet_program_lib.h              |   7 +-
 src/include/gnunet_protocols.h                |   3 +
 src/include/gnunet_resolver_service.h         |   9 +-
 src/include/gnunet_revocation_service.h       |   2 +-
 src/include/gnunet_server_lib.h               |   2 +-
 src/include/gnunet_service_lib.h              |   2 +-
 src/include/gnunet_social_service.h           | 187 +++++++++++++++++-
 src/include/gnunet_statistics_service.h       |   2 +-
 60 files changed, 642 insertions(+), 197 deletions(-)

diff --git a/src/include/block_dns.h b/src/include/block_dns.h
index 459f4b2c0..e43036a48 100644
--- a/src/include/block_dns.h
+++ b/src/include/block_dns.h
@@ -19,7 +19,9 @@
 */
 
 /**
- * @file include/block_dns.h
+ * @file
+ * DNS network structs
+ *
  * @author Christian Grothoff
  */
 #ifndef BLOCK_DNS_H
diff --git a/src/include/block_fs.h b/src/include/block_fs.h
index 0af504627..15610d333 100644
--- a/src/include/block_fs.h
+++ b/src/include/block_fs.h
@@ -19,8 +19,9 @@
 */
 
 /**
- * @file include/block_fs.h
- * @brief fs block formats (shared between fs and block)
+ * @file
+ * FS block formats (shared between FS and Block)
+ *
  * @author Christian Grothoff
  */
 #ifndef BLOCK_FS_H
diff --git a/src/include/block_regex.h b/src/include/block_regex.h
index e8f8cf757..901cc4565 100644
--- a/src/include/block_regex.h
+++ b/src/include/block_regex.h
@@ -19,8 +19,9 @@
 */
 
 /**
- * @file include/block_regex.h
- * @brief regex block formats
+ * @file
+ * regex block formats
+ *
  * @author Bartlomiej Polot
  */
 #ifndef BLOCK_REGEX_H
diff --git a/src/include/gauger.h b/src/include/gauger.h
index 10ada9065..54ba7f1f7 100644
--- a/src/include/gauger.h
+++ b/src/include/gauger.h
@@ -1,4 +1,4 @@
-/** ---------------------------------------------------------------------------
+/* ---------------------------------------------------------------------------
  * This software is in the public domain, furnished "as is", without technical
  * support, and with no warranty, express or implied, as to its usefulness for
  * any purpose.
diff --git a/src/include/gnunet_applications.h b/src/include/gnunet_applications.h
index 067a72f38..0c8837bd4 100644
--- a/src/include/gnunet_applications.h
+++ b/src/include/gnunet_applications.h
@@ -19,8 +19,9 @@
 */
 
 /**
- * @file include/gnunet_applications.h
- * @brief constants for network applications operating on top of the CADET service
+ * @file
+ * Constants for network applications operating on top of the CADET service
+ *
  * @author Christian Grothoff
  */
 
diff --git a/src/include/gnunet_arm_service.h b/src/include/gnunet_arm_service.h
index 6b1682710..b2d234c59 100644
--- a/src/include/gnunet_arm_service.h
+++ b/src/include/gnunet_arm_service.h
@@ -19,9 +19,14 @@
  */
 
 /**
- * @file include/gnunet_arm_service.h
- * @brief API to access gnunet-arm
  * @author Christian Grothoff
+ *
+ * @file
+ * API to access gnunet-arm
+ *
+ * @defgroup arm  ARM service
+ * Automatic Restart Manager
+ * @{
  */
 
 #ifndef GNUNET_ARM_SERVICE_H
@@ -342,6 +347,7 @@ GNUNET_ARM_monitor (const struct GNUNET_CONFIGURATION_Handle *cfg,
 void
 GNUNET_ARM_monitor_disconnect_and_free (struct GNUNET_ARM_MonitorHandle *h);
 
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_ats_plugin.h b/src/include/gnunet_ats_plugin.h
index 71572d64e..19003aa02 100644
--- a/src/include/gnunet_ats_plugin.h
+++ b/src/include/gnunet_ats_plugin.h
@@ -19,14 +19,20 @@
  */
 
 /**
- * @file include/gnunet_ats_plugin.h
- * @brief API for the ATS solvers.  This header
- *        specifies the struct that is given to the plugin's entry
- *        method and the other struct that must be returned.
- *        Note that the destructors of ATS plugins will
- *        be given the value returned by the constructor
- *        and is expected to return a NULL pointer.
  * @author Christian Grothoff
+ *
+ * @file
+ * API for the ATS solvers.
+ *
+ * @defgroup ats-plugin  ATS service plugin API
+ * Plugin API for the ATS service.
+ *
+ * Specifies the struct that is given to the plugin's entry method and the other
+ * struct that must be returned.  Note that the destructors of ATS plugins will
+ * be given the value returned by the constructor and is expected to return a
+ * NULL pointer.
+ *
+ * @{
  */
 #ifndef PLUGIN_ATS_H
 #define PLUGIN_ATS_H
@@ -472,4 +478,6 @@ struct GNUNET_ATS_PluginEnvironment
   unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];
 };
 
+/** @} */  /* end of group */
+
 #endif
diff --git a/src/include/gnunet_ats_service.h b/src/include/gnunet_ats_service.h
index b727b4f9a..acbaabafc 100644
--- a/src/include/gnunet_ats_service.h
+++ b/src/include/gnunet_ats_service.h
@@ -18,10 +18,15 @@
  Boston, MA 02110-1301, USA.
  */
 /**
- * @file include/gnunet_ats_service.h
- * @brief automatic transport selection and outbound bandwidth determination
+ * @file
+ * Automatic transport selection and outbound bandwidth determination
+ *
  * @author Christian Grothoff
  * @author Matthias Wachs
+ *
+ * @defgroup ats  ATS service
+ * Automatic transport selection and outbound bandwidth determination
+ * @{
  */
 #ifndef GNUNET_ATS_SERVICE_H
 #define GNUNET_ATS_SERVICE_H
@@ -695,5 +700,7 @@ GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph,
 				      const struct GNUNET_TIME_Relative scope,
 				      ...);
 
+/** @} */  /* end of group */
+
 #endif
 /* end of file gnunet-service-transport_ats.h */
diff --git a/src/include/gnunet_bandwidth_lib.h b/src/include/gnunet_bandwidth_lib.h
index bed817144..01fd5c0bc 100644
--- a/src/include/gnunet_bandwidth_lib.h
+++ b/src/include/gnunet_bandwidth_lib.h
@@ -19,9 +19,14 @@
 */
 
 /**
- * @file include/gnunet_bandwidth_lib.h
- * @brief functions related to bandwidth (unit)
  * @author Christian Grothoff
+ *
+ * @file
+ * Functions related to bandwidth (unit)
+ *
+ * @defgroup bandwidth  Bandwidth library
+ * Functions related to bandwidth (unit)
+ * @{
  */
 
 #ifndef GNUNET_BANDWIDTH_LIB_H
@@ -327,6 +332,8 @@ GNUNET_BANDWIDTH_tracker_update_quota (struct GNUNET_BANDWIDTH_Tracker *av,
 }
 #endif
 
+/** @} */  /* end of group */
+
 /* ifndef GNUNET_BANDWIDTH_LIB_H */
 #endif
 /* end of gnunet_bandwidth_lib.h */
diff --git a/src/include/gnunet_bio_lib.h b/src/include/gnunet_bio_lib.h
index 7a711649d..034be2ed2 100644
--- a/src/include/gnunet_bio_lib.h
+++ b/src/include/gnunet_bio_lib.h
@@ -19,10 +19,13 @@
 */
 
 /**
- * @file include/gnunet_bio_lib.h
- * @brief buffered IO API
  * @author Christian Grothoff
- * @defgroup bio Buffered binary disk IO (with endianess conversion)
+ *
+ * @file
+ * Buffered IO library
+ *
+ * @defgroup bio  BIO library
+ * Buffered binary disk IO (with endianess conversion)
  * @{
  */
 
diff --git a/src/include/gnunet_block_lib.h b/src/include/gnunet_block_lib.h
index 66c15da05..d42a6dac9 100644
--- a/src/include/gnunet_block_lib.h
+++ b/src/include/gnunet_block_lib.h
@@ -19,9 +19,14 @@
 */
 
 /**
- * @file include/gnunet_block_lib.h
- * @brief library for data block manipulation
  * @author Christian Grothoff
+ *
+ * @file
+ * Library for data block manipulation
+ *
+ * @defgroup block  Block library
+ * Library for data block manipulation
+ * @{
  */
 #ifndef GNUNET_BLOCK_LIB_H
 #define GNUNET_BLOCK_LIB_H
@@ -301,6 +306,8 @@ GNUNET_BLOCK_construct_bloomfilter (int32_t bf_mutator,
 }
 #endif
 
+/** @} */  /* end of group */
+
 
 /* ifndef GNUNET_BLOCK_LIB_H */
 #endif
diff --git a/src/include/gnunet_block_plugin.h b/src/include/gnunet_block_plugin.h
index 35afa8a7f..362d7c740 100644
--- a/src/include/gnunet_block_plugin.h
+++ b/src/include/gnunet_block_plugin.h
@@ -19,13 +19,19 @@
 */
 
 /**
- * @file include/gnunet_block_plugin.h
- * @brief API for block plugins.  Each block plugin must conform to
- *        the API specified by this header.
  * @author Christian Grothoff
- * @defgroup block API to be implemented by applications storing data in the DHT
+ *
+ * @file
+ * API for block plugins.  Each block plugin must conform to the API specified by this header.
+ *
+ * @defgroup block-plugin  Block plugin API
+ * To be implemented by applications storing data in the DHT.
+ *
+ * Each block plugin must conform to the API specified by this header.
+ *
  * @{
  */
+
 #ifndef PLUGIN_BLOCK_H
 #define PLUGIN_BLOCK_H
 
diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h
index a0d28b531..0ba6e2e91 100644
--- a/src/include/gnunet_cadet_service.h
+++ b/src/include/gnunet_cadet_service.h
@@ -18,10 +18,20 @@
      Boston, MA 02110-1301, USA.
 */
 /**
- * @file include/gnunet_cadet_service.h
- * @brief cadet service; establish channels to distant peers
  * @author Christian Grothoff
  * @author Bart Polot
+ *
+ * @file
+ * CADET service; establish channels to distant peers
+ *
+ * @defgroup cadet  CADET service
+ * Confidential Ad-hoc Decentralized End-to-End Transport
+ *
+ * See also:
+ * - [CADET documentation](https://gnunet.org/cadet-subsystem)
+ * - [CADET paper](https://gnunet.org/cadet)
+ *
+ * @{
  */
 #ifndef GNUNET_CADET_SERVICE_H
 #define GNUNET_CADET_SERVICE_H
@@ -632,6 +642,8 @@ GNUNET_CADET_mq_create (struct GNUNET_CADET_Channel *channel);
 }
 #endif
 
+/** @} */  /* end of group */
+
 /* ifndef GNUNET_CADET_SERVICE_H */
 #endif
 /* end of gnunet_cadet_service.h */
diff --git a/src/include/gnunet_client_lib.h b/src/include/gnunet_client_lib.h
index 70dd98504..f961ee181 100644
--- a/src/include/gnunet_client_lib.h
+++ b/src/include/gnunet_client_lib.h
@@ -19,10 +19,13 @@
 */
 
 /**
- * @file include/gnunet_client_lib.h
- * @brief functions related to accessing services
  * @author Christian Grothoff
- * @defgroup client Generic client-side communication with services
+ *
+ * @file
+ * Functions related to accessing services
+
+ * @defgroup client  Client library
+ * Generic client-side communication with services
  * @{
  */
 
diff --git a/src/include/gnunet_client_manager_lib.h b/src/include/gnunet_client_manager_lib.h
index 8f143a770..6838ee046 100644
--- a/src/include/gnunet_client_manager_lib.h
+++ b/src/include/gnunet_client_manager_lib.h
@@ -19,11 +19,17 @@
 */
 
 /**
- * @file include/gnunet_client_manager_lib.h
- * @brief Client manager; higher level client API with transmission queue
- * and message handler registration.
  * @author Gabor X Toth
- * @defgroup client_manager  Higher level client-side communication with services.
+ *
+ * @file
+ * Client manager; higher level client API with transmission queue
+ * and message handler registration.
+ *
+ * @defgroup client-manager  Client manager library
+ * Higher level client-side communication with services.
+ *
+ * Provides a higher level client API
+ * with transmission queue and message handler registration.
  * @{
  */
 #ifndef GNUNET_CLIENT_MANAGER_LIB_H
@@ -347,7 +353,7 @@ GNUNET_CLIENT_MANAGER_op_cancel (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 }
 #endif
 
-/** @} */ /* end of group client_manager */
+/** @} */ /* end of group */
 
 /* ifndef GNUNET_CLIENT_MANAGER_LIB_H */
 #endif
diff --git a/src/include/gnunet_configuration_lib.h b/src/include/gnunet_configuration_lib.h
index 7813096b1..b74aa9520 100644
--- a/src/include/gnunet_configuration_lib.h
+++ b/src/include/gnunet_configuration_lib.h
@@ -19,10 +19,13 @@
 */
 
 /**
- * @file include/gnunet_configuration_lib.h
- * @brief configuration API
  * @author Christian Grothoff
- * @defgroup configuration Configuration management
+ *
+ * @file
+ * Configuration API
+ *
+ * @defgroup configuration  Configuration library
+ * Configuration management
  * @{
  */
 #ifndef GNUNET_CONFIGURATION_LIB_H
diff --git a/src/include/gnunet_connection_lib.h b/src/include/gnunet_connection_lib.h
index 02b2304c9..a91175b8a 100644
--- a/src/include/gnunet_connection_lib.h
+++ b/src/include/gnunet_connection_lib.h
@@ -19,9 +19,14 @@
 */
 
 /**
- * @file include/gnunet_connection_lib.h
- * @brief basic, low-level TCP networking interface
  * @author Christian Grothoff
+ *
+ * @file include/gnunet_connection_lib.h
+ * Basic, low-level TCP networking interface
+ *
+ * @defgroup connection  Connection library
+ * Basic, low-level TCP networking interface
+ * @{
  */
 #ifndef GNUNET_CONNECTION_LIB_H
 #define GNUNET_CONNECTION_LIB_H
@@ -370,7 +375,7 @@ GNUNET_CONNECTION_create_proxied_from_handshake (struct GNUNET_CONNECTION_Handle
 
 
 /**
- * Activate proxied connection and destroy initial proxy handshake connection. 
+ * Activate proxied connection and destroy initial proxy handshake connection.
  * There must not be any pending requests for reading or writing to the
  * proxy hadshake connection at this time.
  *
@@ -387,6 +392,7 @@ GNUNET_CONNECTION_acivate_proxied (struct GNUNET_CONNECTION_Handle *proxied);
 }
 #endif
 
+/** @} */  /* end of group */
 
 /* ifndef GNUNET_CONNECTION_LIB_H */
 #endif
diff --git a/src/include/gnunet_consensus_service.h b/src/include/gnunet_consensus_service.h
index 77607a6e2..aaac12834 100644
--- a/src/include/gnunet_consensus_service.h
+++ b/src/include/gnunet_consensus_service.h
@@ -19,9 +19,14 @@
  */
 
 /**
- * @file include/gnunet_consensus_service.h
- * @brief multi-peer set reconciliation
  * @author Florian Dold
+ *
+ * @file
+ * Multi-peer set reconciliation
+ *
+ * @defgroup consensus  Consensus service
+ * Multi-peer set reconciliation
+ * @{
  */
 
 #ifndef GNUNET_CONSENSUS_SERVICE_H
@@ -166,6 +171,7 @@ GNUNET_CONSENSUS_conclude (struct GNUNET_CONSENSUS_Handle *consensus,
 void
 GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus);
 
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_constants.h b/src/include/gnunet_constants.h
index 0d7614f0b..11c14845a 100644
--- a/src/include/gnunet_constants.h
+++ b/src/include/gnunet_constants.h
@@ -19,9 +19,10 @@
 */
 
 /**
- * @file include/gnunet_constants.h
- * @brief "global" constants for performance tuning
  * @author Christian Grothoff
+ *
+ * @file
+ * "Global" constants for performance tuning
  */
 
 #ifndef GNUNET_CONSTANTS_H
diff --git a/src/include/gnunet_container_lib.h b/src/include/gnunet_container_lib.h
index aa6a17150..3ef64fbb7 100644
--- a/src/include/gnunet_container_lib.h
+++ b/src/include/gnunet_container_lib.h
@@ -19,15 +19,25 @@
 */
 
 /**
- * @file include/gnunet_container_lib.h
- * @brief container classes for GNUnet
  * @author Christian Grothoff
  * @author Nils Durner
- * @defgroup hashmap multi hash-map
- * @defgroup heap min- or max-heap with arbitrary element removal
- * @defgroup bloomfilter Bloom filter (probabilistic set tests)
- * @defgroup dll Doubly-linked list
- * @defgroup metadata Meta data (GNU libextractor key-value pairs)
+ *
+ * @file
+ * Container classes for GNUnet
+ *
+ * @defgroup hashmap  Container library: MultiHashMap
+ * Hash map with multiple values per key.
+ *
+ * @defgroup heap  Container library: Heap
+ * Min- or max-heap with arbitrary element removal
+ *
+ * @defgroup bloomfilter  Container library: Bloom filter
+ * Probabilistic set tests
+ *
+ * @defgroup dll  Container library: Doubly-linked list
+ *
+ * @defgroup metadata  Container library: Metadata
+ * GNU libextractor key-value pairs
  */
 
 #ifndef GNUNET_CONTAINER_LIB_H
diff --git a/src/include/gnunet_conversation_service.h b/src/include/gnunet_conversation_service.h
index 61ccfc03f..15cc0a3d3 100644
--- a/src/include/gnunet_conversation_service.h
+++ b/src/include/gnunet_conversation_service.h
@@ -19,12 +19,15 @@
  */
 
 /**
- * @file include/gnunet_conversation_service.h
- * @brief API to the conversation service
  * @author Simon Dieterle
  * @author Andreas Fuchs
  * @author Christian Grothoff
  *
+ * @file
+ * API to the conversation service
+ *
+ * @defgroup conversation  Conversation service
+ * One-to-one voice communication over CADET
  *
  * NOTE: This API is deliberately deceptively simple; the idea
  * is that advanced features (such as answering machines) will
@@ -41,6 +44,8 @@
  * course provided as part of the basic implementation, as only the
  * CONVERSATION service can know for sure who it is that we are
  * talking to.
+ *
+ * @{
  */
 #ifndef GNUNET_CONVERSATION_SERVICE_H
 #define GNUNET_CONVERSATION_SERVICE_H
@@ -417,6 +422,7 @@ GNUNET_CONVERSATION_call_resume (struct GNUNET_CONVERSATION_Call *call,
 void
 GNUNET_CONVERSATION_call_stop (struct GNUNET_CONVERSATION_Call *call);
 
+/** @} */  /* end of group */
 
 #if 0				/* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_core_service.h b/src/include/gnunet_core_service.h
index 8f2ff738b..3dd3e2b2d 100644
--- a/src/include/gnunet_core_service.h
+++ b/src/include/gnunet_core_service.h
@@ -18,11 +18,13 @@
      Boston, MA 02110-1301, USA.
 */
 /**
- * @file include/gnunet_core_service.h
- * @brief core service; this is the main API for encrypted P2P
- *        communications
  * @author Christian Grothoff
- * @defgroup core encrypted direct communication between peers
+ *
+ * @file include/gnunet_core_service.h
+ * Core service; the main API for encrypted P2P communications
+ *
+ * @defgroup core  Core service
+ * Encrypted direct communication between peers
  * @{
  */
 #ifndef GNUNET_CORE_SERVICE_H
diff --git a/src/include/gnunet_crypto_lib.h b/src/include/gnunet_crypto_lib.h
index 2ec3b4d8d..4e6dc93ab 100644
--- a/src/include/gnunet_crypto_lib.h
+++ b/src/include/gnunet_crypto_lib.h
@@ -28,8 +28,10 @@
  * @author Ioana Patrascu
  * @author Tzvetan Horozov
  *
- * @defgroup crypto Cryptographic operations
- * @defgroup hash Hashing and operations on hashes
+ * @defgroup crypto  Crypto library: cryptographic operations
+ *
+ * @defgroup hash  Crypto library: hash operations
+ * Hashing and operations on hashes
  */
 
 #ifndef GNUNET_CRYPTO_LIB_H
diff --git a/src/include/gnunet_datacache_lib.h b/src/include/gnunet_datacache_lib.h
index 6334935cc..28efa9627 100644
--- a/src/include/gnunet_datacache_lib.h
+++ b/src/include/gnunet_datacache_lib.h
@@ -19,13 +19,19 @@
 */
 
 /**
- * @file include/gnunet_datacache_lib.h
- * @brief datacache is a simple, transient hash table
- *        of bounded size with content expiration.
- *        In contrast to the sqstore there is
- *        no prioritization, deletion or iteration.
- *        All of the data is discarded when the peer shuts down!
  * @author Christian Grothoff
+ *
+ * @file
+ * datacache API
+ *
+ * @defgroup datacache  Datacache library
+ * Simple, transient hash table of bounded size with content expiration.
+ *
+ * In contrast to the sqstore there is
+ * no prioritization, deletion or iteration.
+ * All of the data is discarded when the peer shuts down!
+ *
+ * @{
  */
 
 #ifndef GNUNET_DATACACHE_LIB_H
@@ -171,6 +177,7 @@ GNUNET_DATACACHE_get_closest (struct GNUNET_DATACACHE_Handle *h,
                               GNUNET_DATACACHE_Iterator iter,
                               void *iter_cls);
 
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_datacache_plugin.h b/src/include/gnunet_datacache_plugin.h
index 699973b0c..cda4e88ce 100644
--- a/src/include/gnunet_datacache_plugin.h
+++ b/src/include/gnunet_datacache_plugin.h
@@ -19,9 +19,14 @@
 */
 
 /**
- * @file include/gnunet_datacache_plugin.h
- * @brief API for database backends for the datacache
  * @author Christian Grothoff
+ *
+ * @file
+ * API for database backends for the datacache
+ *
+ * @defgroup datacache-plugin  Datacache plugin API
+ * API for database backends for the datacache
+ * @{
  */
 #ifndef PLUGIN_DATACACHE_H
 #define PLUGIN_DATACACHE_H
@@ -181,6 +186,7 @@ struct GNUNET_DATACACHE_PluginFunctions
 
 };
 
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_datastore_plugin.h b/src/include/gnunet_datastore_plugin.h
index 08093d55e..7e5344ebf 100644
--- a/src/include/gnunet_datastore_plugin.h
+++ b/src/include/gnunet_datastore_plugin.h
@@ -19,9 +19,14 @@
 */
 
 /**
- * @file include/gnunet_datastore_plugin.h
- * @brief API for the database backend plugins.
  * @author Christian Grothoff
+ *
+ * @file
+ * API for the database backend plugins.
+ *
+ * @defgroup datastore-plugin  Datastore service plugin API
+ * API for the database backend plugins.
+ * @{
  */
 #ifndef PLUGIN_DATASTORE_H
 #define PLUGIN_DATASTORE_H
@@ -48,8 +53,8 @@
  * @param delta change in disk utilization,
  *        0 for "reset to empty"
  */
-typedef void 
-(*GNUNET_DATASTORE_DiskUtilizationChange) (void *cls, 
+typedef void
+(*GNUNET_DATASTORE_DiskUtilizationChange) (void *cls,
 					   int delta);
 
 
@@ -93,13 +98,13 @@ struct GNUNET_DATASTORE_PluginEnvironment
  * @return #GNUNET_OK to keep the item
  *         #GNUNET_NO to delete the item
  */
-typedef int 
-(*PluginDatumProcessor) (void *cls, 
+typedef int
+(*PluginDatumProcessor) (void *cls,
 			 const struct GNUNET_HashCode *key,
-			 uint32_t size, 
+			 uint32_t size,
 			 const void *data,
 			 enum GNUNET_BLOCK_Type type,
-			 uint32_t priority, 
+			 uint32_t priority,
 			 uint32_t anonymity,
 			 struct GNUNET_TIME_Absolute expiration,
 			 uint64_t uid);
@@ -130,11 +135,11 @@ typedef void
  * @param status #GNUNET_OK or #GNUNET_SYSERROR
  * @param msg error message on error
  */
-typedef void 
-(*PluginPutCont) (void *cls, 
+typedef void
+(*PluginPutCont) (void *cls,
 		  const struct GNUNET_HashCode *key,
 		  uint32_t size,
-		  int status, 
+		  int status,
 		  const char *msg);
 
 
@@ -155,16 +160,16 @@ typedef void
  * @param cont continuation called with success or failure status
  * @param cont_cls continuation closure for @a cont
  */
-typedef void 
+typedef void
 (*PluginPut) (void *cls, const struct GNUNET_HashCode *key,
 	      uint32_t size,
 	      const void *data,
 	      enum GNUNET_BLOCK_Type type,
-	      uint32_t priority, 
+	      uint32_t priority,
 	      uint32_t anonymity,
 	      uint32_t replication,
 	      struct GNUNET_TIME_Absolute expiration,
-	      PluginPutCont cont, 
+	      PluginPutCont cont,
 	      void *cont_cls);
 
 
@@ -175,7 +180,7 @@ typedef void
  * @param key key in the data store, if NULL iteration is finished
  * @param count how many values are stored under this key in the datastore
  */
-typedef void 
+typedef void
 (*PluginKeyProcessor) (void *cls,
 		       const struct GNUNET_HashCode *key,
 		       unsigned int count);
@@ -211,8 +216,8 @@ typedef void
  *        proc should be called with NULL if there is no result
  * @param proc_cls closure for @a proc
  */
-typedef void 
-(*PluginGetKey) (void *cls, 
+typedef void
+(*PluginGetKey) (void *cls,
 		 uint64_t offset,
 		 const struct GNUNET_HashCode *key,
 		 const struct GNUNET_HashCode *vhash,
@@ -231,8 +236,8 @@ typedef void
  * @param proc function to call the value (once only).
  * @param proc_cls closure for @a proc
  */
-typedef void 
-(*PluginGetRandom) (void *cls, 
+typedef void
+(*PluginGetRandom) (void *cls,
 		    PluginDatumProcessor proc,
 		    void *proc_cls);
 
@@ -244,8 +249,8 @@ typedef void
  * @param status #GNUNET_OK or #GNUNET_SYSERROR
  * @param msg error message on error
  */
-typedef void 
-(*PluginUpdateCont) (void *cls, 
+typedef void
+(*PluginUpdateCont) (void *cls,
 		     int status,
 		     const char *msg);
 
@@ -270,12 +275,12 @@ typedef void
  * @param cont continuation called with success or failure status
  * @param cons_cls continuation closure
  */
-typedef void 
+typedef void
 (*PluginUpdate) (void *cls,
 		 uint64_t uid,
 		 int delta,
 		 struct GNUNET_TIME_Absolute expire,
-		 PluginUpdateCont cont, 
+		 PluginUpdateCont cont,
 		 void *cont_cls);
 
 
@@ -291,7 +296,7 @@ typedef void
  * @param proc function to call on the matching value
  * @param proc_cls closure for @a proc
  */
-typedef void 
+typedef void
 (*PluginGetType) (void *cls,
 		  uint64_t offset,
 		  enum GNUNET_BLOCK_Type type,
@@ -304,7 +309,7 @@ typedef void
  *
  * @param cls closure
  */
-typedef void 
+typedef void
 (*PluginDrop) (void *cls);
 
 
@@ -384,5 +389,6 @@ struct GNUNET_DATASTORE_PluginFunctions
 
 };
 
+/** @} */  /* end of group */
 
 #endif
diff --git a/src/include/gnunet_datastore_service.h b/src/include/gnunet_datastore_service.h
index 14ffb1740..bdc12b26c 100644
--- a/src/include/gnunet_datastore_service.h
+++ b/src/include/gnunet_datastore_service.h
@@ -19,13 +19,21 @@
 */
 
 /**
- * @file include/gnunet_datastore_service.h
- * @brief API that can be used manage the
- *   datastore for files stored on a GNUnet node;
- *   note that the datastore is NOT responsible for
- *   on-demand encoding, that is achieved using
- *   a special kind of entry.
  * @author Christian Grothoff
+ *
+ * @file
+ * datastore service
+ *
+ * @defgroup datastore  Datastore service
+ * Data store for files stored on a GNUnet node.
+ *
+ * Provides an API that can be used manage the
+ * datastore for files stored on a GNUnet node.
+ * Note that the datastore is NOT responsible for
+ * on-demand encoding, that is achieved using
+ * a special kind of entry.
+ *
+ * @{
  */
 
 #ifndef GNUNET_DATASTORE_SERVICE_H
@@ -389,6 +397,7 @@ GNUNET_DATASTORE_get_for_replication (struct GNUNET_DATASTORE_Handle *h,
 void
 GNUNET_DATASTORE_cancel (struct GNUNET_DATASTORE_QueueEntry *qe);
 
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_dht_service.h b/src/include/gnunet_dht_service.h
index c5b980ba9..36463f488 100644
--- a/src/include/gnunet_dht_service.h
+++ b/src/include/gnunet_dht_service.h
@@ -19,10 +19,13 @@
  */
 
 /**
- * @file include/gnunet_dht_service.h
- * @brief API to the DHT service
  * @author Christian Grothoff
- * @defgroup dht Distributed Hash Table
+ *
+ * @file
+ * API to the DHT service
+ *
+ * @defgroup dht  DHT service
+ * Distributed Hash Table
  * @{
  */
 
@@ -414,8 +417,8 @@ typedef void (*GNUNET_DHT_ActMaliciousContinuation)(void *cls,
           FIXME: perhaps make this an enum of known malicious behaviors?
  */
 struct GNUNET_DHT_ActMaliciousHandle *
-GNUNET_DHT_act_malicious (struct GNUNET_DHT_Handle *handle, 
-                      unsigned int action, 
+GNUNET_DHT_act_malicious (struct GNUNET_DHT_Handle *handle,
+                      unsigned int action,
                       GNUNET_DHT_PutContinuation cont,
                       void *cont_cls);
 #endif
diff --git a/src/include/gnunet_disk_lib.h b/src/include/gnunet_disk_lib.h
index 4b38a31d6..7b0b0e998 100644
--- a/src/include/gnunet_disk_lib.h
+++ b/src/include/gnunet_disk_lib.h
@@ -18,9 +18,14 @@
      Boston, MA 02110-1301, USA.
 */
 /**
- * @file include/gnunet_disk_lib.h
- * @brief disk IO apis
  * @author Christian Grothoff
+ *
+ * @file
+ * Disk IO APIs
+ *
+ * @defgroup disk  Disk library
+ * Disk IO APIs
+ * @{
  */
 #ifndef GNUNET_DISK_LIB_H
 #define GNUNET_DISK_LIB_H
@@ -861,6 +866,7 @@ GNUNET_DISK_file_sync (const struct GNUNET_DISK_FileHandle *h);
 }
 #endif
 
+/** @} */  /* end of group */
 
 /* ifndef GNUNET_DISK_LIB_H */
 #endif
diff --git a/src/include/gnunet_dns_service.h b/src/include/gnunet_dns_service.h
index edf5cf182..4a8956e84 100644
--- a/src/include/gnunet_dns_service.h
+++ b/src/include/gnunet_dns_service.h
@@ -19,9 +19,13 @@
  */
 
 /**
- * @file include/gnunet_dns_service.h
- * @brief API to access the DNS service.
  * @author Christian Grothoff
+ *
+ * @file
+ * API to access the DNS service.
+ *
+ * @defgroup dns  DNS service
+ * @{
  */
 #ifndef GNUNET_DNS_SERVICE_H
 #define GNUNET_DNS_SERVICE_H
@@ -153,7 +157,7 @@ GNUNET_DNS_request_drop (struct GNUNET_DNS_RequestHandle *rh);
  * @param reply reply data
  */
 void
-GNUNET_DNS_request_answer (struct GNUNET_DNS_RequestHandle *rh,		
+GNUNET_DNS_request_answer (struct GNUNET_DNS_RequestHandle *rh,
 			   uint16_t reply_length,
 			   const char *reply);
 
@@ -182,4 +186,6 @@ GNUNET_DNS_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 void
 GNUNET_DNS_disconnect (struct GNUNET_DNS_Handle *dh);
 
+/** @} */  /* end of group */
+
 #endif
diff --git a/src/include/gnunet_dnsparser_lib.h b/src/include/gnunet_dnsparser_lib.h
index e800442dc..9680af329 100644
--- a/src/include/gnunet_dnsparser_lib.h
+++ b/src/include/gnunet_dnsparser_lib.h
@@ -19,10 +19,15 @@
  */
 
 /**
- * @file include/gnunet_dnsparser_lib.h
- * @brief API for helper library to parse DNS packets.
  * @author Philipp Toelke
  * @author Christian Grothoff
+ *
+ * @file
+ * API for helper library to parse DNS packets.
+ *
+ * @defgroup dns-parser  DNS parser library
+ * Helper library to parse DNS packets.
+ * @{
  */
 #ifndef GNUNET_DNSPARSER_LIB_H
 #define GNUNET_DNSPARSER_LIB_H
@@ -883,5 +888,6 @@ size_t
 GNUNET_DNSPARSER_hex_to_bin (const char *hex,
                              void *data);
 
+/** @} */  /* end of group */
 
 #endif
diff --git a/src/include/gnunet_dnsstub_lib.h b/src/include/gnunet_dnsstub_lib.h
index 164df18c6..08029cebf 100644
--- a/src/include/gnunet_dnsstub_lib.h
+++ b/src/include/gnunet_dnsstub_lib.h
@@ -19,9 +19,14 @@
  */
 
 /**
- * @file include/gnunet_dnsstub_lib.h
- * @brief API for helper library to send DNS requests to DNS resolver
  * @author Christian Grothoff
+ *
+ * @file
+ * API for helper library to send DNS requests to DNS resolver
+ *
+ * @defgroup dns-stub  DNS stub library
+ * Helper library to send DNS requests to DNS resolver
+ * @{
  */
 #ifndef GNUNET_DNSSTUB_LIB_H
 #define GNUNET_DNSSTUB_LIB_H
@@ -122,4 +127,6 @@ GNUNET_DNSSTUB_resolve2 (struct GNUNET_DNSSTUB_Context *ctx,
 void
 GNUNET_DNSSTUB_resolve_cancel (struct GNUNET_DNSSTUB_RequestSocket *rs);
 
+/** @} */  /* end of group */
+
 #endif
diff --git a/src/include/gnunet_dv_service.h b/src/include/gnunet_dv_service.h
index f694c17ea..aa33408ce 100644
--- a/src/include/gnunet_dv_service.h
+++ b/src/include/gnunet_dv_service.h
@@ -20,8 +20,15 @@
 
 /**
  * @author Christian Grothoff
- * @file include/gnunet_dv_service.h
- * @brief DV service API (should only be used by the DV plugin)
+ *
+ * @file
+ * DV service API (should only be used by the DV plugin)
+ *
+ * @defgroup dv  DV service
+ * Distance vector routing
+ *
+ * The DV service API should only be used by the DV plugin.
+ * @{
  */
 #ifndef GNUNET_SERVICE_DV_H
 #define GNUNET_SERVICE_DV_H
@@ -165,5 +172,6 @@ GNUNET_DV_send (struct GNUNET_DV_ServiceHandle *sh,
 void
 GNUNET_DV_send_cancel (struct GNUNET_DV_TransmitHandle *th);
 
+/** @} */  /* end of group */
 
 #endif
diff --git a/src/include/gnunet_env_lib.h b/src/include/gnunet_env_lib.h
index 408a19a56..75fd62bbe 100644
--- a/src/include/gnunet_env_lib.h
+++ b/src/include/gnunet_env_lib.h
@@ -19,10 +19,18 @@
  */
 
 /**
- * @file include/gnunet_env_lib.h
- * @brief Library providing operations for the @e environment of
- *        PSYC and Social messages, and for (de)serializing variable values.
  * @author Gabor X Toth
+ *
+ * @file
+ * Environment library
+ *
+ * @defgroup env  Environment library
+ * Environment data structure for PSYC and Social messages.
+ *
+ * Library providing operations for the @e environment of
+ * PSYC and Social messages, and for (de)serializing variable values.
+ *
+ * @{
  */
 
 
@@ -326,6 +334,8 @@ GNUNET_ENV_value_from_dict (struct GNUNET_CONTAINER_MultiHashMap *dict, size_t *
 }
 #endif
 
+/** @} */  /* end of group */
+
 /* ifndef GNUNET_ENV_LIB_H */
 #endif
 /* end of gnunet_env_lib.h */
diff --git a/src/include/gnunet_fragmentation_lib.h b/src/include/gnunet_fragmentation_lib.h
index f39ad26a0..b408de3bf 100644
--- a/src/include/gnunet_fragmentation_lib.h
+++ b/src/include/gnunet_fragmentation_lib.h
@@ -18,11 +18,16 @@
      Boston, MA 02110-1301, USA.
 */
 /**
- * @file include/gnunet_fragmentation_lib.h
- * @brief library to help fragment messages
  * @author Christian Grothoff
  *
- * TODO: consider additional flow-control for sending from
+ * @file
+ * Library to help fragment messages
+ *
+ * @defgroup fragmentation  Fragmentation library
+ * Library to help fragment messages
+ * @{
+ *
+ * @todo Consider additional flow-control for sending from
  *       fragmentation based on continuations.
  */
 
@@ -213,6 +218,8 @@ GNUNET_DEFRAGMENT_process_fragment (struct GNUNET_DEFRAGMENT_Context *dc,
                                     const struct GNUNET_MessageHeader *msg);
 
 
+/** @} */  /* end of group */
+
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif
diff --git a/src/include/gnunet_friends_lib.h b/src/include/gnunet_friends_lib.h
index 0a757c4ef..2d8d231a5 100644
--- a/src/include/gnunet_friends_lib.h
+++ b/src/include/gnunet_friends_lib.h
@@ -19,9 +19,14 @@
 */
 
 /**
- * @file include/gnunet_friends_lib.h
- * @brief library to read and write the FRIENDS file
  * @author Christian Grothoff
+ *
+ * @file
+ * Library to read and write the FRIENDS file
+ *
+ * @defgroup friends  Friends library
+ * Library to read and write the FRIENDS file
+ * @{
  */
 #ifndef GNUNET_FRIENDS_LIB_H
 #define GNUNET_FRIENDS_LIB_H
@@ -99,8 +104,9 @@ int
 GNUNET_FRIENDS_write (struct GNUNET_FRIENDS_Writer *w,
                       const struct GNUNET_PeerIdentity *friend_id);
 
+/** @} */  /* end of group */
 
-					  #if 0                           /* keep Emacsens' auto-indent happy */
+#if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif
 #ifdef __cplusplus
diff --git a/src/include/gnunet_fs_service.h b/src/include/gnunet_fs_service.h
index 26757e558..736a67ae3 100644
--- a/src/include/gnunet_fs_service.h
+++ b/src/include/gnunet_fs_service.h
@@ -18,9 +18,14 @@
      Boston, MA 02110-1301, USA.
 */
 /**
- * @file include/gnunet_fs_service.h
- * @brief API for file-sharing via GNUnet
  * @author Christian Grothoff
+ *
+ * @file
+ * API for file sharing via GNUnet
+ *
+ * @defgroup fs FS service
+ * File sharing
+ * @{
  */
 #ifndef GNUNET_FS_LIB_H
 #define GNUNET_FS_LIB_H
@@ -2746,7 +2751,7 @@ struct GNUNET_FS_ShareTreeItem
 
 
 /**
- * Opaqe handle to an asynchronous directory scanning activity.
+ * Opaque handle to an asynchronous directory scanning activity.
  */
 struct GNUNET_FS_DirScanner;
 
@@ -2809,6 +2814,7 @@ GNUNET_FS_share_tree_trim (struct GNUNET_FS_ShareTreeItem *toplevel);
 void
 GNUNET_FS_share_tree_free (struct GNUNET_FS_ShareTreeItem *toplevel);
 
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_getopt_lib.h b/src/include/gnunet_getopt_lib.h
index 11916ac80..59b0c9d4c 100644
--- a/src/include/gnunet_getopt_lib.h
+++ b/src/include/gnunet_getopt_lib.h
@@ -19,10 +19,13 @@
 */
 
 /**
- * @file include/gnunet_getopt_lib.h
- * @brief command line parsing and --help formatting
  * @author Christian Grothoff
- * @defgroup getopt command-line parsing
+ *
+ * @file
+ * Command line parsing and --help formatting
+ *
+ * @defgroup getopt  Getopt library
+ * Command line parsing and --help formatting
  * @{
  */
 
diff --git a/src/include/gnunet_gns_service.h b/src/include/gnunet_gns_service.h
index c4b4a4962..b24d9a64a 100644
--- a/src/include/gnunet_gns_service.h
+++ b/src/include/gnunet_gns_service.h
@@ -19,9 +19,14 @@
  */
 
 /**
- * @file include/gnunet_gns_service.h
- * @brief API to the GNS service
  * @author Martin Schanzenbach
+ *
+ * @file
+ * API to the GNS service
+ *
+ * @defgroup gns  GNS service
+ * GNU Name System
+ * @{
  */
 #ifndef GNUNET_GNS_SERVICE_H
 #define GNUNET_GNS_SERVICE_H
@@ -101,7 +106,7 @@ enum GNUNET_GNS_LocalOptions
    * Never look in the DHT, keep request to local cache.
    */
   GNUNET_GNS_LO_NO_DHT = 1,
-  
+
   /**
    * For the rightmost label, only look in the cache (it
    * is our master zone), for the others, the DHT is OK.
@@ -147,6 +152,7 @@ GNUNET_GNS_lookup (struct GNUNET_GNS_Handle *handle,
 void
 GNUNET_GNS_lookup_cancel (struct GNUNET_GNS_LookupRequest *lr);
 
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_gnsrecord_lib.h b/src/include/gnunet_gnsrecord_lib.h
index 718365f95..110646563 100644
--- a/src/include/gnunet_gnsrecord_lib.h
+++ b/src/include/gnunet_gnsrecord_lib.h
@@ -19,9 +19,14 @@
 */
 
 /**
- * @file include/gnunet_gnsrecord_lib.h
- * @brief API that can be used to manipulate GNS record data
  * @author Christian Grothoff
+ *
+ * @file
+ * API that can be used to manipulate GNS record data
+ *
+ * @defgroup gns-record  GNS record library
+ * Manipulate GNS record data
+ * @{
  */
 #ifndef GNUNET_GNSRECORD_LIB_H
 #define GNUNET_GNSRECORD_LIB_H
@@ -558,7 +563,7 @@ struct GNUNET_TIME_Absolute
 GNUNET_GNSRECORD_record_get_expiration_time (unsigned int rd_count,
 					     const struct GNUNET_GNSRECORD_Data *rd);
 
-
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_gnsrecord_plugin.h b/src/include/gnunet_gnsrecord_plugin.h
index b0b492634..7315ec879 100644
--- a/src/include/gnunet_gnsrecord_plugin.h
+++ b/src/include/gnunet_gnsrecord_plugin.h
@@ -19,11 +19,15 @@
 */
 
 /**
- * @file include/gnunet_gnsrecord_plugin.h
- * @brief plugin API for GNS record types
  * @author Christian Grothoff
- * @defgroup gnsrecordplugin API to be implemented by applications defining new GNS record types
- * @{ */
+ *
+ * @file
+ * Plugin API for GNS record types
+ *
+ * @defgroup gns-record-plugin  GNS record plugin API
+ * To be implemented by applications defining new record types.
+ * @{
+ */
 #ifndef GNUNET_GNSRECORD_PLUGIN_H
 #define GNUNET_GNSRECORD_PLUGIN_H
 
@@ -129,8 +133,7 @@ struct GNUNET_GNSRECORD_PluginFunctions
 
 };
 
-
-/** @} */ /* end of group gnsrecordplugin */
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_hello_lib.h b/src/include/gnunet_hello_lib.h
index f7f4780f0..506566d40 100644
--- a/src/include/gnunet_hello_lib.h
+++ b/src/include/gnunet_hello_lib.h
@@ -19,9 +19,13 @@
 */
 
 /**
- * @file include/gnunet_hello_lib.h
- * @brief helper library for handling HELLOs
  * @author Christian Grothoff
+ * @file
+ * Helper library for handling HELLOs
+ *
+ * @defgroup hello  Hello library
+ * Helper library for handling HELLOs
+ * @{
  */
 
 #ifndef GNUNET_HELLO_LIB_H
@@ -439,6 +443,8 @@ GNUNET_HELLO_parse_uri (const char *uri,
                         struct GNUNET_HELLO_Message **hello,
                         GNUNET_HELLO_TransportPluginsFind plugins_find);
 
+/** @} */  /* end of group */
+
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif
diff --git a/src/include/gnunet_helper_lib.h b/src/include/gnunet_helper_lib.h
index 7cccecad5..1fee1ac01 100644
--- a/src/include/gnunet_helper_lib.h
+++ b/src/include/gnunet_helper_lib.h
@@ -19,11 +19,19 @@
 */
 
 /**
- * @file include/gnunet_helper_lib.h
- * @brief API for dealing with (SUID) helper processes that communicate via
- *          GNUNET_MessageHeaders on stdin/stdout
  * @author Philipp Toelke
  * @author Christian Grothoff
+ *
+ * @file
+ * API for dealing with SUID helper processes
+ *
+ * @defgroup helper  Helper library
+ * Dealing with SUID helper processes.
+ *
+ * Provides an API for dealing with (SUID) helper processes
+ * that communicate via GNUNET_MessageHeaders on STDIN/STDOUT.
+ *
+ * @{
  */
 
 #ifndef GNUNET_HELPER_LIB_H
@@ -166,5 +174,7 @@ GNUNET_HELPER_send (struct GNUNET_HELPER_Handle *h,
 void
 GNUNET_HELPER_send_cancel (struct GNUNET_HELPER_SendHandle *sh);
 
+/** @} */  /* end of group */
+
 #endif
 /* end of include guard: GNUNET_HELPER_LIB_H */
diff --git a/src/include/gnunet_identity_provider_service.h b/src/include/gnunet_identity_provider_service.h
index a923f5c2f..1e05244c8 100644
--- a/src/include/gnunet_identity_provider_service.h
+++ b/src/include/gnunet_identity_provider_service.h
@@ -19,19 +19,12 @@
 */
 
 /**
- * @file include/gnunet_identity_provider_service.h
- * @brief Identity provider service; implements identity provider for GNUnet
  * @author Martin Schanzenbach
  *
- * Egos in GNUnet are ECDSA keys.  You assume an ego by using (signing
- * with) a particular private key.  As GNUnet users are expected to
- * have many egos, we need an identity service to allow users to
- * manage their egos.  The identity service manages the egos (private
- * keys) of the local user; it does NOT manage egos of other users
- * (public keys).  For giving names to other users and manage their
- * public keys securely, we use GNS.
+ * @file
+ * Identity provider service; implements identity provider for GNUnet
  *
- * @defgroup identity-provider service
+ * @defgroup identity-provider  Identity provider service
  * @{
  */
 #ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H
diff --git a/src/include/gnunet_identity_service.h b/src/include/gnunet_identity_service.h
index f1a4b31e9..4622e20a9 100644
--- a/src/include/gnunet_identity_service.h
+++ b/src/include/gnunet_identity_service.h
@@ -19,10 +19,14 @@
 */
 
 /**
- * @file include/gnunet_identity_service.h
- * @brief Identity service; implements identity management for GNUnet
  * @author Christian Grothoff
  *
+ * @file
+ * Identity service; implements identity management for GNUnet
+ *
+ * @defgroup identity  Identity service
+ * Identity management.
+ *
  * Egos in GNUnet are ECDSA keys.  You assume an ego by using (signing
  * with) a particular private key.  As GNUnet users are expected to
  * have many egos, we need an identity service to allow users to
@@ -31,7 +35,6 @@
  * (public keys).  For giving names to other users and manage their
  * public keys securely, we use GNS.
  *
- * @defgroup identity identity management service
  * @{
  */
 #ifndef GNUNET_IDENTITY_SERVICE_H
diff --git a/src/include/gnunet_load_lib.h b/src/include/gnunet_load_lib.h
index 986e82656..22e327bf7 100644
--- a/src/include/gnunet_load_lib.h
+++ b/src/include/gnunet_load_lib.h
@@ -19,9 +19,14 @@
 */
 
 /**
- * @file include/gnunet_load_lib.h
- * @brief functions related to load calculations
  * @author Christian Grothoff
+ *
+ * @file
+ * Functions related to load calculations
+ *
+ * @defgroup load  Load library
+ * Load calculations.
+ * @{
  */
 
 #ifndef GNUNET_LOAD_LIB_H
@@ -106,6 +111,7 @@ GNUNET_LOAD_get_average (struct GNUNET_LOAD_Value *load);
 void
 GNUNET_LOAD_update (struct GNUNET_LOAD_Value *load, uint64_t data);
 
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_microphone_lib.h b/src/include/gnunet_microphone_lib.h
index 96a5e5f07..0d84bfdfc 100644
--- a/src/include/gnunet_microphone_lib.h
+++ b/src/include/gnunet_microphone_lib.h
@@ -19,11 +19,16 @@
  */
 
 /**
- * @file include/gnunet_microphone_lib.h
- * @brief API to access an audio microphone; provides access to hardware microphones
  * @author Simon Dieterle
  * @author Andreas Fuchs
  * @author Christian Grothoff
+ *
+ * @file
+ * API to access an audio microphone; provides access to hardware microphones
+ *
+ * @defgroup microphone  Microphone library
+ * Provides access to hardware microphones.
+ * @{
  */
 #ifndef GNUNET_MICROPHONE_SERVICE_H
 #define GNUNET_MICROPHONE_SERVICE_H
@@ -124,6 +129,7 @@ GNUNET_MICROPHONE_create_from_hardware (const struct GNUNET_CONFIGURATION_Handle
 void
 GNUNET_MICROPHONE_destroy (struct GNUNET_MICROPHONE_Handle *microphone);
 
+/** @} */  /* end of group */
 
 #if 0				/* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_mq_lib.h b/src/include/gnunet_mq_lib.h
index 5936f3ca2..1c16b8630 100644
--- a/src/include/gnunet_mq_lib.h
+++ b/src/include/gnunet_mq_lib.h
@@ -20,9 +20,12 @@
 
 /**
  * @author Florian Dold
- * @file include/gnunet_mq_lib.h
- * @brief general purpose message queue
- * @defgroup mq general purpose message queue
+ *
+ * @file
+ * General-purpose message queue
+ *
+ * @defgroup mq  MQ library
+ * General-purpose message queue
  * @{
  */
 #ifndef GNUNET_MQ_H
diff --git a/src/include/gnunet_multicast_service.h b/src/include/gnunet_multicast_service.h
index 5503eb3a9..a8e4a99f6 100644
--- a/src/include/gnunet_multicast_service.h
+++ b/src/include/gnunet_multicast_service.h
@@ -19,10 +19,15 @@
 */
 
 /**
- * @file include/gnunet_multicast_service.h
- * @brief multicast service; establish tunnels to distant peers
- * @author Christian Grothoff
  * @author Gabor X Toth
+ * @author Christian Grothoff
+ *
+ * @file
+ * Multicast service; multicast messaging via CADET
+ *
+ * @defgroup multicast  Multicast service
+ * Multicast messaging via CADET.
+ * @{
  */
 
 #ifndef GNUNET_MULTICAST_SERVICE_H
@@ -897,6 +902,7 @@ GNUNET_MULTICAST_member_to_origin_resume (struct GNUNET_MULTICAST_MemberTransmit
 void
 GNUNET_MULTICAST_member_to_origin_cancel (struct GNUNET_MULTICAST_MemberTransmitHandle *th);
 
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_mysql_lib.h b/src/include/gnunet_mysql_lib.h
index 96e3b9e49..83b10cf79 100644
--- a/src/include/gnunet_mysql_lib.h
+++ b/src/include/gnunet_mysql_lib.h
@@ -18,9 +18,14 @@
      Boston, MA 02110-1301, USA.
 */
 /**
- * @file include/gnunet_mysql_lib.h
- * @brief library to help with access to a MySQL database
  * @author Christian Grothoff
+ *
+ * @file
+ * Helper library to access a MySQL database
+ *
+ * @defgroup mysql  MySQL library
+ * Helper library to access a MySQL database.
+ * @{
  */
 #ifndef GNUNET_MYSQL_LIB_H
 #define GNUNET_MYSQL_LIB_H
@@ -202,6 +207,7 @@ GNUNET_MYSQL_statement_run_prepared (struct GNUNET_MYSQL_Context *mc,
 				     struct GNUNET_MYSQL_StatementHandle *sh,
 				     unsigned long long *insert_id, ...);
 
+/** @} */  /* end of group */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_nse_service.h b/src/include/gnunet_nse_service.h
index 4e4c10987..365b35d9b 100644
--- a/src/include/gnunet_nse_service.h
+++ b/src/include/gnunet_nse_service.h
@@ -22,12 +22,13 @@
 #define GNUNET_NSE_SERVICE_H_
 
 /**
- * @file include/gnunet_nse_service.h
- * @brief API to retrieve the current network size estimate,
- *        also to register for notifications whenever a new
- *        network size estimate is calculated.
+ * @file
+ * API to retrieve the current network size estimate,
+ * also to register for notifications whenever a new
+ * network size estimate is calculated.
+ *
  * @author Nathan Evans
- * @defgroup nse network size estimation service
+ * @defgroup nse  Network size estimation service
  * @{
  */
 
diff --git a/src/include/gnunet_os_lib.h b/src/include/gnunet_os_lib.h
index 431988042..bb0840029 100644
--- a/src/include/gnunet_os_lib.h
+++ b/src/include/gnunet_os_lib.h
@@ -19,8 +19,9 @@
 */
 
 /**
- * @file include/gnunet_os_lib.h
- * @brief low level process routines
+ * @file
+ * Low level process routines
+ *
  * @author Christian Grothoff
  * @author Krista Bennett
  * @author Gerd Knorr <kraxel@bytesex.org>
diff --git a/src/include/gnunet_program_lib.h b/src/include/gnunet_program_lib.h
index ac176f42c..85c802285 100644
--- a/src/include/gnunet_program_lib.h
+++ b/src/include/gnunet_program_lib.h
@@ -19,10 +19,11 @@
 */
 
 /**
- * @file include/gnunet_program_lib.h
- * @brief functions related to starting programs
+ * @file
+ * Functions related to starting programs
+ *
  * @author Christian Grothoff
- * @defgroup program functions for writing command-line programs
+ * @defgroup program  Functions for writing command-line programs
  * @{
  */
 
diff --git a/src/include/gnunet_protocols.h b/src/include/gnunet_protocols.h
index 2d1fbbd62..a3e4199a4 100644
--- a/src/include/gnunet_protocols.h
+++ b/src/include/gnunet_protocols.h
@@ -2640,6 +2640,9 @@ extern "C"
 /** S->C: notify about an existing place */
 #define GNUNET_MESSAGE_TYPE_SOCIAL_APP_PLACE 854
 
+/** S->C:  */
+#define GNUNET_MESSAGE_TYPE_SOCIAL_HOST_RELAY 855
+
 /*******************************************************************************
  * X-VINE DHT messages
  ******************************************************************************/
diff --git a/src/include/gnunet_resolver_service.h b/src/include/gnunet_resolver_service.h
index bb63fb86f..3806cbdcf 100644
--- a/src/include/gnunet_resolver_service.h
+++ b/src/include/gnunet_resolver_service.h
@@ -19,10 +19,13 @@
 */
 
 /**
- * @file include/gnunet_resolver_service.h
- * @brief functions related to doing DNS lookups
  * @author Christian Grothoff
- * @defgroup resolver asynchronous standard DNS lookups
+ *
+ * @file
+ * Functions related to doing DNS lookups
+ *
+ * @defgroup resolver  Resolver service
+ * Asynchronous standard DNS lookups
  * @{
  */
 
diff --git a/src/include/gnunet_revocation_service.h b/src/include/gnunet_revocation_service.h
index c7f487fd4..919f62db9 100644
--- a/src/include/gnunet_revocation_service.h
+++ b/src/include/gnunet_revocation_service.h
@@ -25,7 +25,7 @@
  * @file include/gnunet_revocation_service.h
  * @brief API to perform and access key revocations
  * @author Christian Grothoff
- * @defgroup revocation key revocation service
+ * @defgroup revocation  Key revocation service
  * @{
  */
 
diff --git a/src/include/gnunet_server_lib.h b/src/include/gnunet_server_lib.h
index 71ab07e08..b1be9ee3a 100644
--- a/src/include/gnunet_server_lib.h
+++ b/src/include/gnunet_server_lib.h
@@ -22,7 +22,7 @@
  * @file include/gnunet_server_lib.h
  * @brief library for building GNUnet network servers
  * @author Christian Grothoff
- * @defgroup server functions for a server that communicates with clients
+ * @defgroup server  Functions for a server that communicates with clients
  * @{
  */
 
diff --git a/src/include/gnunet_service_lib.h b/src/include/gnunet_service_lib.h
index 6cb7413d3..9f3947dda 100644
--- a/src/include/gnunet_service_lib.h
+++ b/src/include/gnunet_service_lib.h
@@ -22,7 +22,7 @@
  * @file include/gnunet_service_lib.h
  * @brief functions related to starting services
  * @author Christian Grothoff
- * @defgroup service generic functions for implementing service processes
+ * @defgroup service  Generic functions for implementing service processes
  * @{
  */
 
diff --git a/src/include/gnunet_social_service.h b/src/include/gnunet_social_service.h
index bde3dbceb..c5e55bbab 100644
--- a/src/include/gnunet_social_service.h
+++ b/src/include/gnunet_social_service.h
@@ -19,11 +19,191 @@
 */
 
 /**
- * @file include/gnunet_social_service.h
- * @brief Social service; implements social interactions using the PSYC service.
  * @author Gabor X Toth
  * @author Christian Grothoff
+ *
+ * @file
+ * Social service; implements social interactions through the PSYC service.
  */
+
+/** @defgroup social Social service
+Social interactions through the PSYC service.
+
+# Overview
+
+The social service provides an API for social interactions based on a one-to-many messaging model.
+It manages subscriptions of applications to places, provides messaging functionality in places,
+allows access to the local message history and manages the GNS zone of _egos_ (user identities).
+
+The service stores private and public keys of subscribed places, as well as files received in subscribed places.
+
+# Concepts and terminology
+
+## Ego, Nym
+
+An _ego_ is an identity of a user, a private-public key pair.
+A _nym_ is an identity of another user in the network, identified by its public key.
+Each user can have multiple identities.
+
+struct GNUNET_SOCIAL_Ego and struct GNUNET_SOCIAL_Nym represents one of these identities.
+
+## Place, Host, Guest
+
+A _place_ is where social interactions happen.  It is owned and created by an _ego_.
+Creating a new place happens by an _ego_ entering a new place as a _host_,
+where _guests_ can enter later to receive messages sent to the place.
+
+A place is identified by its public key.
+
+- struct GNUNET_SOCIAL_Host represents a place entered as host,
+- struct GNUNET_SOCIAL_Guest is used for a place entered as guest.
+- A struct GNUNET_SOCIAL_Place can be obtained for both a host and guest place
+  using GNUNET_SOCIAL_host_get_place() and GNUNET_SOCIAL_guest_get_place()
+  and can be used with API functions common to hosts and guests.
+
+## History
+
+Messages sent to places are stored locally by the PSYCstore service, and can be queried any time.
+GNUNET_SOCIAL_history_replay_latest() retrieves the latest N messages sent to the place,
+while GNUNET_SOCIAL_history_replay() is used to query a given message ID range.
+
+## GNU Name System
+
+The GNU Name System is used for assigning human-readable names to nyms and places.
+There's a _GNS zone_ corresponding to each _nym_.
+An _ego_ can publish PKEY and PLACE records in its own zone, pointing to nyms and places, respectively.
+
+## Announcement, talk request
+
+The host can _announce_ messages to the place, using GNUNET_SOCIAL_host_announce().
+Guests can send _talk_ requests to the host, using GNUNET_SOCIAL_guest_talk().
+The host receives talk requests of guests and can _relay_ them to the place,
+or process it using a message handler function.
+
+# Using the API
+
+## Connecting to the service
+
+A client first establishes an _application connection_ to the service using
+GNUNET_SOCIAL_app_connect() providing its _application ID_, then receives the
+public keys of subscribed places and available egos and in response.
+
+## Reconnecting to places
+
+Then the application can reconnect to its subscribed places by establishing
+_place connections_ with GNUNET_SOCIAL_host_enter_reconnect() and
+GNUNET_SOCIAL_guest_enter_reconnect().
+
+## Subscribing to a place
+
+Entering and subscribing a new host or guest place is done using
+GNUNET_SOCIAL_host_enter() and GNUNET_SOCIAL_guest_enter().
+
+## Disconnecting from a place
+
+An application can disconnect from a place while the social service keeps its
+network connection active, using GNUNET_SOCIAL_host_disconnect() and
+GNUNET_SOCIAL_guest_disconnect().
+
+## Leaving a place
+
+To permanently leave a place, see GNUNET_SOCIAL_host_leave() and GNUNET_SOCIAL_guest_leave().
+When leaving a place its network connections are closed and all applications are unsubscribed from the place.
+
+# Methods
+
+## _message
+
+A message sent to the place.
+
+### Environment
+
+#### _id_reply_to
+message ID this message is in reply to.
+
+#### _id_thread
+
+thread ID, the first message ID in the thread.
+
+#### _nym_author__
+nym of the author.
+
+#### _sig_author
+signature of the message body and its variables by the author.
+
+## Data
+
+Message body.
+
+## _notice_place
+
+Notification about a place.
+
+TODO: Applications can decide to auto-subscribe to certain places,
+e.g. files under a given size.
+
+### Environment
+
+#### Using GNS
+
+##### _gns_place
+GNS name of the place in a globally unique .zkey zone
+
+#### Without GNS
+
+##### _key_pub_place
+public key of place
+
+##### _peer_origin
+peer ID of origin
+
+##### _list_peer_relays
+list of peer IDs of relays
+
+## _notice_place_file
+
+Notification about a place hosting a file.
+
+### Environment
+
+The environment of _notice_place above, plus the following:
+
+#### _size_file
+size of file
+
+#### _mime_file
+MIME type of file
+
+#### _name_file
+name of file
+
+#### _description_file
+description of file
+
+## _file
+
+Messages with a _file method contain a file,
+which is saved to disk upon receipt at the following location:
+$GNUNET_DATA_HOME/social/files/<H(place_pub)>/<message_id>
+
+### Environment
+
+#### _size_file
+size of file
+
+#### _mime_file
+MIME type of file
+
+#### _name_file
+name of file
+
+#### _description_file
+description
+
+@{
+*/
+
+
 #ifndef GNUNET_SOCIAL_SERVICE_H
 #define GNUNET_SOCIAL_SERVICE_H
 
@@ -371,7 +551,7 @@ typedef void
  *        Message part, as it arrived from the network.
  * @param message_id
  *        Message ID this data fragment belongs to.
- * @param cancelled.
+ * @param cancelled
  *        #GNUNET_YES if the message was cancelled,
  *        #GNUNET_NO  if the message is complete.
  */
@@ -1334,6 +1514,7 @@ GNUNET_SOCIAL_zone_add_nym (const struct GNUNET_SOCIAL_App *app,
                             GNUNET_ResultCallback result_cb,
                             void *result_cls);
 
+/** @} */  /* end of group social */
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
diff --git a/src/include/gnunet_statistics_service.h b/src/include/gnunet_statistics_service.h
index 35c938eb9..a5f5bdb20 100644
--- a/src/include/gnunet_statistics_service.h
+++ b/src/include/gnunet_statistics_service.h
@@ -24,7 +24,7 @@
  *        the operation of GNUnet; all statistical values
  *        must be of type `unsigned long long`.
  * @author Christian Grothoff
- * @defgroup statistics track statistics or provide access to statistics
+ * @defgroup statistics  Track statistics or provide access to statistics
  * @{
  */
 
-- 
2.25.1