4 files changed, 642 insertions, 521 deletions

diff --git a/src/include/gnunet_multicast_service.h b/src/include/gnunet_multicast_service.h
index da0e09e2f..f58d38bab 100644
--- a/src/include/gnunet_multicast_service.h
+++ b/src/include/gnunet_multicast_service.h
@@ -18,7 +18,7 @@
      Boston, MA 02111-1307, USA.
 */
 
-/**
+/** 
  * @file include/gnunet_multicast_service.h
  * @brief multicast service; establish tunnels to distant peers
  * @author Christian Grothoff
@@ -38,35 +38,35 @@ extern "C"
 #include "gnunet_util_lib.h"
 #include "gnunet_transport_service.h"
 
-/**
+/** 
  * Version number of GNUnet-multicast API.
  */
 #define GNUNET_MULTICAST_VERSION 0x00000000
 
 
-/**
+/** 
  * Opaque handle for a multicast group member.
  */
 struct GNUNET_MULTICAST_Member;
 
-/**
+/** 
  * Handle for the origin of a multicast group.
  */
 struct GNUNET_MULTICAST_Origin;
 
-/**
+/** 
  * Group membership policies.
  */
 enum GNUNET_MULTICAST_JoinPolicy
 {
-  /**
-   * Anyone can join the group, without announcing his presence; all
-   * messages are always public and can be distributed freely.  Joins
-   * may be announced, but this is not required.
+  /** 
+   * Anyone can join the group, without announcing his presence;
+   * all messages are always public and can be distributed freely.
+   * Joins may be announced, but this is not required.
    */
   GNUNET_MULTICAST_JP_ANONYMOUS = 0,
 
-  /**
+  /** 
    * Origin must approve membership to the group, messages must only be
    * distributed to current group members.  This includes the group
    * state as well as transient messages.
@@ -74,13 +74,13 @@ enum GNUNET_MULTICAST_JoinPolicy
   GNUNET_MULTICAST_JP_PRIVATE = 1
 
 #if IDEAS_FOR_FUTURE
-  /**
+  /** 
    * Anyone can freely join the group (no approval required); however,
    * transient messages must only be distributed to current group
    * members, so the origin must still acknowledge that the member
    * joined before transient messages are delivered.  As approval is
-   * guaranteed, the presistent group state can de synchronized freely
-   * immediately, prior to origin confirmation
+   * guaranteed, the presistent group state can be synchronized freely
+   * immediately, prior to origin confirmation.
    */
   GNUNET_MULTICAST_JP_OPEN = 2
 #endif
@@ -88,45 +88,46 @@ enum GNUNET_MULTICAST_JoinPolicy
 };
 
 
-/**
+/** 
  * Opaque handle to a replay request from the multicast service.
  */
 struct GNUNET_MULTICAST_ReplayHandle;
 
 
-/**
+/** 
  * Functions with this signature are called whenever the multicast
  * service needs a message to be replayed.  Implementations of this
- * function MUST call 'GNUNET_MULTICAST_replay' ONCE (with a message
+ * function MUST call GNUNET_MULTICAST_replay() ONCE (with a message
  * or an error); however, if the origin is destroyed or the group is
  * left, the replay handle must no longer be used.
  *
- * @param cls closure (set from GNUNET_MULTICAST_origin_start/join)
- * @param message_id which message should be replayed
- * @param rh handle to pass to message transmit function
+ * @param cls Closure (set from GNUNET_MULTICAST_origin_start()
+ *            or GNUNET_MULTICAST_member_join()).
+ * @param message_id Which message should be replayed.
+ * @param rh Handle to pass to message transmit function.
  */
 typedef void (*GNUNET_MULTICAST_ReplayCallback) (void *cls,
                                                  uint64_t message_id,
                                                  struct GNUNET_MULTICAST_ReplayHandle *rh);
 
 
-/**
+/** 
  * Possible error codes during replay.
  */
 enum GNUNET_MULTICAST_ReplayErrorCode
 {
-  
-  /**
+
+  /** 
    * Everything is fine.
    */ 
   GNUNET_MULTICAST_REC_OK = 0,
 
-  /**
+  /** 
    * Message has been discarded (likely transient message that was too old).
    */ 
   GNUNET_MULTICAST_REC_TRANSIENT_LOST = 1,
 
-  /**
+  /** 
    * Message ID counter was larger than the highest counter this
    * replay function has ever encountered; thus it is likely the
    * origin never sent it and we're at the HEAD of the multicast
@@ -134,7 +135,7 @@ enum GNUNET_MULTICAST_ReplayErrorCode
    */ 
   GNUNET_MULTICAST_REC_PAST_HEAD = 2,
 
-  /**
+  /** 
    * Internal error (i.e. database error).  Try some other peer.
    */ 
   GNUNET_MULTICAST_REC_INTERNAL_ERROR = 3
@@ -144,80 +145,81 @@ enum GNUNET_MULTICAST_ReplayErrorCode
 
 GNUNET_NETWORK_STRUCT_BEGIN
 
-/**
- * Header of a multicast message.  This format is public as the replay
- * mechanism must replay messages using the same format.  This is
- * needed as we want to integrity-check messages within the multicast
- * layer to avoid multicasting mal-formed messages.
+/** 
+ * Header of a multicast message.
+ *
+ * This format is public as the replay mechanism must replay messages using the
+ * same format.  This is needed as we want to integrity-check messages within
+ * the multicast layer to avoid multicasting mal-formed messages.
  */
 struct GNUNET_MULTICAST_MessageHeader
 {
 
-  /**
+  /** 
    * Header for all multicast messages from the origin.
    */
   struct GNUNET_MessageHeader header;
 
-  /**
-   * How many hops has this message taken since the origin?
-   * (helpful to determine shortest paths to the origin for responses
-   *  among honest peers; updated at each hop and thus not signed
-   *  and not secure)
+  /** 
+   * Number of hops this message has taken since the origin.
+   *
+   * Helpful to determine shortest paths to the origin for responses among
+   * honest peers; updated at each hop and thus not signed and not secure.
    */
   uint32_t hop_counter GNUNET_PACKED;
 
-  /**
-   * ECC signature of the message.  Signature must match the public
-   * key of the multicast group.
+  /** 
+   * ECC signature of the message.
+   *
+   * Signature must match the public key of the multicast group.
    */
   struct GNUNET_CRYPTO_EccSignature signature;
 
-  /**
+  /** 
    * Signature of the multicast message.
    */
   struct GNUNET_CRYPTO_EccSignaturePurpose purpose;
 
-  /**
+  /** 
    * Number of the message, monotonically increasing.
    */
   uint64_t message_id GNUNET_PACKED;
 
-  /**
-   * Counter that monotonically increases whenever a member
-   * leaves the group.
+  /** 
+   * Counter that monotonically increases whenever a member leaves the group.
    */
   uint64_t group_generation GNUNET_PACKED;
 
-  /**
-   * Difference between the current message_id and the message_id of
-   * the preceeding non-transient message.  Zero for transient
-   * messages, UINT64_MAX for the first message, or any other message
-   * creating a full state reset by the origin.  By subtracting
-   * 'state_delta' from 'message_id', it is possible to calculate the
-   * message ID of the preceeding non-transient message and thus
-   * quickly traverse all state changes up to the last full state
-   * reset by the origin.  This is useful as it allows joining clients
-   * to quickly reassemble the state while skipping over transient
-   * messages (and doing so without having to trust intermediaries to
-   * do it right, as the indices in the chain are signed).  If the
-   * state chain is getting too long, the origin can choose to
-   * originate a state message with a state_delta of UINT64_MAX,
-   * thereby starting a new chain.  The origin will then have to
-   * re-create the full state with state update messages following the
-   * state reset message.
+  /** 
+   * Difference between the current @a message_id and the @a message_id of the
+   * preceeding non-transient message.
+   * 
+   * Zero for transient messages, @c UINT64_MAX for the first message, or any
+   * other message creating a full state reset by the origin.  By subtracting
+   * @a state_delta from @a message_id, it is possible to calculate the message
+   * ID of the preceeding non-transient message and thus quickly traverse all
+   * state changes up to the last full state reset by the origin.  This is
+   * useful as it allows joining clients to quickly reassemble the state while
+   * skipping over transient messages (and doing so without having to trust
+   * intermediaries to do it right, as the indices in the chain are signed).  If
+   * the state chain is getting too long, the origin can choose to originate a
+   * state message with a state_delta of UINT64_MAX, thereby starting a new
+   * chain.  The origin will then have to re-create the full state with state
+   * update messages following the state reset message.
    *
-   * Open question: needed in multicast, or just have this in PSYC;
-   * still might be useful for selective fetching of messages.
-   * Still, that again should that not be done by PSYC?
+   * Open question: needed in multicast, or just have this in PSYC; still might
+   * be useful for selective fetching of messages.  Still, that again should
+   * that not be done by PSYC?
    */
   uint64_t state_delta GNUNET_PACKED;
 
-  /**
-   * Header for the message body.  Three message types are
-   * specifically understood by multicast, namely "peer join", "peer
-   * leave", and "group terminated".  Multicast will use those
-   * messages to update its list of candidates for content
-   * distribution.  All other message types are application-specific.
+  /** 
+   * Header for the message body.
+   *
+   * Three message types are specifically understood by multicast, namely "peer
+   * join", "peer leave", and "group terminated".  Multicast will use those
+   * messages to update its list of candidates for content distribution.  All
+   * other message types are application-specific.
    */
   struct GNUNET_MessageHeader body;
 
@@ -227,12 +229,12 @@ struct GNUNET_MULTICAST_MessageHeader
 GNUNET_NETWORK_STRUCT_END
 
 
-/**
+/** 
  * Replay a message from the multicast group.
  *
- * @param rh replay handle identifying which replay operation was requested
- * @param msg replayed message, NULL if unknown/error
- * @param ec error code
+ * @param rh Replay handle identifying which replay operation was requested.
+ * @param msg Replayed message, NULL if unknown/error.
+ * @param ec Error code.
  */
 void
 GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh,
@@ -240,28 +242,31 @@ GNUNET_MULTICAST_replay (struct GNUNET_MULTICAST_ReplayHandle *rh,
                          enum GNUNET_MULTICAST_ReplayErrorCode ec);
 
 
-/**
- * Handle that identifies a join request (to match calls to the
- * 'GNUNET_MULTICAST_MembershipChangeCallback' to the corresponding
- * calls to 'GNUNET_MULTICAST_join_decision').
+/** 
+ * Handle that identifies a join request.
+ *
+ * Used to match calls to #GNUNET_MULTICAST_MembershipChangeCallback to the
+ * corresponding calls to GNUNET_MULTICAST_join_decision().
  */
 struct GNUNET_MULTICAST_JoinHande;
 
 
-/**
- * Function to call with the decision made for a membership change
- * request.  Must be called once and only once in response to an
- * invocation of the 'GNUNET_MULTICAST_MembershipChangeCallback'.
+/** 
+ * Function to call with the decision made for a membership change request.
  *
- * @param jh join request handle
- * @param join_response message to send in response to the joining peer;
+ * Must be called once and only once in response to an invocation of the
+ * #GNUNET_MULTICAST_MembershipChangeCallback.
+ *
+ * @param jh Join request handle.
+ * @param join_response Message to send in response to the joining peer;
  *        can also be used to redirect the peer to a different group at the
  *        application layer; this response is to be transmitted to the
  *        peer that issued the request even if admission is denied.
- * @param is_admitted GNUNET_OK if joining is approved, GNUNET_SYSERR if it is disapproved;
- *         GNUNET_NO for peers leaving 
- * @param relay_count number of relays given
- * @param relays array of suggested peers that might be useful relays to use
+ * @param is_admitted #GNUNET_OK if joining is approved,
+ *        #GNUNET_SYSERR if it is disapproved;
+ *        #GNUNET_NO for peers leaving.
+ * @param relay_count Number of relays given.
+ * @param relays Array of suggested peers that might be useful relays to use
  *        when joining the multicast group (essentially a list of peers that
  *        are already part of the multicast group and might thus be willing
  *        to help with routing).  If empty, only this local peer (which must
@@ -277,19 +282,21 @@ GNUNET_MULTICAST_join_decision (struct GNUNET_MULTICAST_JoinHandle *jh,
                                 const struct GNUNET_PeerIdentity *relays);
 
 
-/**
- * Method called whenever another peer wants to join or has left a 
- * multicast group.  Implementations of this function must call
- * 'GNUNET_MULTICAST_join_decision' with the decision.
+/** 
+ * Method called whenever another peer wants to join or has left a multicast
+ * group.
  *
- * @param cls closure
- * @param peer identity of the peer that wants to join or leave
- * @param join_req application-dependent join message from the new user
- *        (might, for example, contain a user 
+ * Implementations of this function must call GNUNET_MULTICAST_join_decision()
+ * with the decision.
+ *
+ * @param cls Closure.
+ * @param peer Identity of the peer that wants to join or leave.
+ * @param join_req Application-dependent join message from the new user
+ *        (might, for example, contain a user,
  *        bind user identity/pseudonym to peer identity, application-level
- *        message to origin, etc.)
- * @param is_joining GNUNET_YES if the peer wants to join, GNUNET_NO if the peer left
- * @param jh join handle to pass to 'GNUNET_MULTICAST_join_decison'
+ *        message to origin, etc.).
+ * @param is_joining #GNUNET_YES if the peer wants to join, #GNUNET_NO if the peer left.
+ * @param jh Join handle to pass to GNUNET_MULTICAST_join_decison().
  */
 typedef void (*GNUNET_MULTICAST_MembershipChangeCallback)(void *cls,
                                                           const struct GNUNET_PeerIdentity *peer,
@@ -298,31 +305,31 @@ typedef void (*GNUNET_MULTICAST_MembershipChangeCallback)(void *cls,
                                                           struct GNUNET_MULTICAST_JoinHandle *jh);
 
 
-/**
+/** 
  * Handle to pass back for the answer of a membership test.
  */
 struct GNUNET_MULTICAST_MembershipTestHandle;
 
 
-/**
+/** 
  * Call informing multicast about the decision taken for membership test.
  *
- * @param mth handle that was given for the query
- * @param decision GNUNET_YES if peer was a member, GNUNET_NO if peer was not a member,
- *         GNUNET_SYSERR if we cannot answer the membership test
+ * @param mth Handle that was given for the query.
+ * @param decision #GNUNET_YES if peer was a member, #GNUNET_NO if peer was not a member,
+ *         #GNUNET_SYSERR if we cannot answer the membership test.
  */
 void
 GNUNET_MULTICAST_membership_test_answer (struct GNUNET_MULTICAST_MembershipTestHandle *mth,
                                          int decision);
 
 
-/**
+/** 
  * Method called to test if a member was in the group at a particular time.
  *
- * @param cls closure
- * @param peer identity of the peer that we want to test
- * @param message_id message ID for which we want to do the test
- * @param mth handle to give to 'GNUNET_MULTICAST_membership_test_answer'
+ * @param cls Closure.
+ * @param peer Identity of the peer that we want to test.
+ * @param message_id Message ID for which we want to do the test.
+ * @param mth Handle to give to GNUNET_MULTICAST_membership_test_answer().
  */
 typedef void (*GNUNET_MULTICAST_MembershipTestCallback)(void *cls,
                                                         const struct GNUNET_PeerIdentity *peer,
@@ -330,14 +337,14 @@ typedef void (*GNUNET_MULTICAST_MembershipTestCallback)(void *cls,
                                                         struct GNUNET_MULTICAST_MembershipTestHandle *mth);
 
 
-/**
+/** 
  * Function called whenever a group member has transmitted a message
  * to the origin (other than joining or leaving).
  *
- * @param cls closure (set from GNUNET_MULTICAST_origin_start)
- * @param sender identity of the sender
- * @param response_id unique counter for the response from this sender to this origin
- * @param msg message to the origin
+ * @param cls Closure (set from GNUNET_MULTICAST_origin_start).
+ * @param sender Identity of the sender.
+ * @param response_id Unique counter for the response from this sender to this origin.
+ * @param msg Message to the origin.
  */
 typedef void (*GNUNET_MULTICAST_ResponseCallback) (void *cls,
                                                    const struct GNUNET_PeerIdentity *sender,
@@ -345,48 +352,51 @@ typedef void (*GNUNET_MULTICAST_ResponseCallback) (void *cls,
                                                    const struct GNUNET_MessageHeader *msg);
 
 
-/**
+/** 
  * Function called whenever a group member is receiving a message from
  * the origin.  If admission to the group is denied, this function is
- * called once with the response of the 'origin' (as given to 
- * 'GNUNET_MULTICAST_join_decision') and then a second time with "NULL"
+ * called once with the response of the @e origin (as given to 
+ * GNUNET_MULTICAST_join_decision()) and then a second time with NULL
  * to indicate that the connection failed for good.
  *
- * @param cls closure (set from GNUNET_MULTICAST_member_join)
- * @param message_id unique number of the message, 0 for response to join request,
+ * @param cls Closure (set from GNUNET_MULTICAST_member_join())
+ * @param message_id Unique number of the message, 0 for response to join request,
  *        normal message IDs in either direction start at 1.
- * @param msg message from the origin, NULL if the origin shut down
- *        (or we were kicked out, and we should thus call GNUNET_MULTICAST_member_leave next)
+ * @param msg Message from the origin, NULL if the origin shut down
+ *        (or we were kicked out, and we should thus call
+ *        GNUNET_MULTICAST_member_leave() next)
  */
 typedef void (*GNUNET_MULTICAST_MulticastMessageCallback) (void *cls,
                                                            uint64_t message_id,
                                                            const struct GNUNET_MULTICAST_MessageHeader *msg);
 
 
-/**
- * Start a multicast group.  Will advertise the origin in the P2P
- * overlay network under the respective public key so that other peer
- * can find this peer to join it.  Peers that issue
- * 'GNUNET_MULTICAST_member_join' can then transmit a join request to
- * either an existing group member (if the 'join_policy' is
- * permissive) or to the origin.  If the joining is approved, the
- * member is cleared for 'replay' and will begin to receive messages
- * transmitted to the group.  If joining is disapproved, the failed
- * candidate will be given a response.  Members in the group can send
- * messages to the origin (one at a time).
+/** 
+ * Start a multicast group.
  *
- * @param cfg configuration to use
- * @param cls closure for the various callbacks that follow
+ * Will advertise the origin in the P2P overlay network under the respective
+ * public key so that other peer can find this peer to join it.  Peers that
+ * issue GNUNET_MULTICAST_member_join() can then transmit a join request to
+ * either an existing group member (if the @a join_policy is permissive) or to
+ * the origin.  If the joining is approved, the member is cleared for @e replay
+ * and will begin to receive messages transmitted to the group.  If joining is
+ * disapproved, the failed candidate will be given a response.  Members in the
+ * group can send messages to the origin (one at a time).
+ *
+ * @param cfg Configuration to use.
+ * @param cls Closure for the various callbacks that follow.
  * @param priv_key ECC key that will be used to sign messages for this
  *                 multicast session; public key is used to identify the
  *                 multicast group; FIXME: we'll likely want to use
- *                 NOT the p521 curve here, but a cheaper one in the future
- * @param join_policy what is the membership policy of the group?
- * @param replay_cb function that can be called to replay a message
- * @param test_cb function multicast can use to test group membership
- * @param join_cb function called to approve / disapprove joining of a peer
- * @param response_cb function called with messages from group members
- * @return handle for the origin, NULL on error 
+ *                 NOT the p521 curve here, but a cheaper one in the future.
+ * @param join_policy What is the membership policy of the group?
+ * @param replay_cb Function that can be called to replay a message.
+ * @param test_cb Function multicast can use to test group membership.
+ * @param join_cb Function called to approve / disapprove joining of a peer,
+ *                and to inform about a leaving member.
+ * @param leave_cb Function called to inform about a leaving member.
+ * @param response_cb Function called with messages from group members.
+ * @return Handle for the origin, NULL on error.
  */
 struct GNUNET_MULTICAST_Origin *
 GNUNET_MULTICAST_origin_start (const struct GNUNET_CONFIGURATION_Handle *cfg, 
@@ -399,21 +409,21 @@ GNUNET_MULTICAST_origin_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
                                GNUNET_MULTICAST_ResponseCallback response_cb);
 
 
-/**
+/** 
  * Handle for a request to send a message to all multicast group members
  * (from the origin).
  */
 struct GNUNET_MULTICAST_MulticastRequest;
 
 
-/**
+/** 
  * Send a message to the multicast group.
  *
- * @param origin handle to the multicast group
- * @param size number of bytes to transmit
- * @param cb function to call to get the message
- * @param cb_cls closure for 'cb'
- * @return NULL on error (i.e. request already pending)
+ * @param origin Handle to the multicast group.
+ * @param size Number of bytes to transmit.
+ * @param cb Function to call to get the message.
+ * @param cb_cls Closure for @a cb.
+ * @return NULL on error (i.e. request already pending).
  */
 struct GNUNET_MULTICAST_MulticastRequest *
 GNUNET_MULTICAST_origin_to_all (struct GNUNET_MULTICAST_Origin *origin,
@@ -422,16 +432,16 @@ GNUNET_MULTICAST_origin_to_all (struct GNUNET_MULTICAST_Origin *origin,
                                 void *cb_cls);
 
 
-/**
+/** 
  * Cancel request for message transmission to multicast group.
  *
- * @param mr request to cancel
+ * @param mr Request to cancel.
  */
 void
 GNUNET_MULTICAST_origin_to_all_cancel (struct GNUNET_MULTICAST_MulticastRequest *mr);
 
 
-/**
+/** 
  * End a multicast group.
  *
  * @param origin multicast group to terminate
@@ -440,41 +450,42 @@ void
 GNUNET_MULTICAST_origin_end (struct GNUNET_MULTICAST_Origin *origin);
 
 
-/**
- * Join a multicast group.  The entity joining is always the local
- * peer.  Further information about the candidate can be provided in
- * the 'join_req' message.  If the join fails, the 'message_cb' is
- * invoked with a (failure) response and then with 'NULL'.  If the
- * join succeeds, outstanding (state) messages and ongoing multicast
- * messages will be given to the 'message_cb' until the member decides
- * to leave the group.  The 'test_cb' and 'replay_cb' functions may be
- * called at anytime by the multicast service to support relaying
- * messages to other members of the group.
+/** 
+ * Join a multicast group.
+ *
+ * The entity joining is always the local peer.  Further information about the
+ * candidate can be provided in the @a join_req message.  If the join fails, the
+ * @a message_cb is invoked with a (failure) response and then with NULL.  If
+ * the join succeeds, outstanding (state) messages and ongoing multicast
+ * messages will be given to the @a message_cb until the member decides to leave
+ * the group.  The @a test_cb and @a replay_cb functions may be called at
+ * anytime by the multicast service to support relaying messages to other
+ * members of the group.
  *
- * @param cfg configuration to use
- * @param cls closure for callbacks
- * @param pub_key ECC key that identifies the group
- * @param max_known_message_id largest known message ID to the replay service;
+ * @param cfg Configuration to use.
+ * @param cls Closure for callbacks.
+ * @param pub_key ECC key that identifies the group.
+ * @param max_known_message_id Largest known message ID to the replay service;
  *        all messages with IDs larger than this ID will be replayed if
  *        possible (lower IDs will be considered known and thus only
- *        be replayed upon explicit request)
- * @param max_known_state_message_id largest known message ID with a non-zero
- *                       value for the 'state_delta'; state messages with
+ *        be replayed upon explicit request).
+ * @param max_known_state_message_id Largest known message ID with a non-zero
+ *        value for the @e state_delta; state messages with
  *        larger IDs than this value will be replayed with high priority
  *        (lower IDs will be considered known and thus only
- *        be replayed upon explicit request)
- * @param replay_cb function that can be called to replay messages
+ *        be replayed upon explicit request).
+ * @param replay_cb Function that can be called to replay messages
  *        this peer already knows from this group; NULL if this
- *        client is unable to support replay
- * @param test_cb function multicast can use to test group membership
- * @param message_cb function to be called for all messages we 
- *        receive from the group, excluding those our replay_cb
- *        already has
- * @param join_req application-dependent join message to be passed to origin
+ *        client is unable to support replay.
+ * @param test_cb Function multicast can use to test group membership.
+ * @param message_cb Function to be called for all messages we 
+ *        receive from the group, excluding those our @a replay_cb
+ *        already has.
+ * @param join_req Application-dependent join message to be passed to origin
  *        (might, for example, contain a user 
  *        bind user identity/pseudonym to peer identity, application-level
- *        message to origin, etc.)
- * @return handle for the member, NULL on error 
+ *        message to origin, etc.).
+ * @return Handle for the member, NULL on error.
  */
 struct GNUNET_MULTICAST_Member *
 GNUNET_MULTICAST_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg, 
@@ -488,22 +499,23 @@ GNUNET_MULTICAST_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg,
                               const struct GNUNET_MessageHeader *join_req);
 
 
-/**
+/** 
  * Handle for a replay request.
  */
 struct GNUNET_MULTICAST_ReplayRequest;
 
 
-/**
- * Request a message to be replayed.  Useful if messages below
- * the 'max_known_*_id's given when joining are needed and not
- * known to the client.
+/** 
+ * Request a message to be replayed.
+ *
+ * Useful if messages below the @e max_known_*_id's given when joining are
+ * needed and not known to the client.
  *
- * @param member membership handle
- * @param message_id ID of a message that this client would like to see replayed
- * @param message_cb function to be called for the replayed message
- * @param message_cb_cls closure for 'message_cb'
- * @return replay request handle, NULL on error
+ * @param member Membership handle.
+ * @param message_id ID of a message that this client would like to see replayed.
+ * @param message_cb Function to be called for the replayed message.
+ * @param message_cb_cls Closure for @a message_cb.
+ * @return Replay request handle, NULL on error.
  */
 struct GNUNET_MULTICAST_ReplayRequest *
 GNUNET_MULTICAST_member_request_replay (struct GNUNET_MULTICAST_Member *member,
@@ -512,38 +524,38 @@ GNUNET_MULTICAST_member_request_replay (struct GNUNET_MULTICAST_Member *member,
                                         void *message_cb_cls);
 
 
-/**
+/** 
  * Cancel a replay request.
  *
- * @param rr request to cancel
+ * @param rr Request to cancel.
  */
 void
 GNUNET_MULTICAST_member_request_replay_cancel (struct GNUNET_MULTICAST_ReplayRequest *rr);
 
 
-/**
- * Leave a mutlicast group.
+/** 
+ * Leave a multicast group.
  *
- * @param member membership handle
+ * @param member Membership handle.
  */
 void
 GNUNET_MULTICAST_member_leave (struct GNUNET_MULTICAST_Member *member);
 
 
-/**
+/** 
  * Handle for a message to be delivered to the origin.
  */
 struct GNUNET_MULTICAST_ResponseRequest;
 
 
-/**
+/** 
  * Send a message to the origin of the multicast group.  
  * 
- * @param member membership handle
- * @param size number of bytes we want to send to origin
- * @param cb callback to call to get the message
- * @param cb_cls closure for 'cb'
- * @return handle to cancel request, NULL on error (i.e. request already pending)
+ * @param member Membership handle.
+ * @param size Number of bytes we want to send to origin.
+ * @param cb Callback to call to get the message.
+ * @param cb_cls Closure for @a cb.
+ * @return Handle to cancel request, NULL on error (i.e. request already pending).
  */
 struct GNUNET_MULTICAST_ResponseRequest *
 GNUNET_MULTICAST_member_to_origin (struct GNUNET_MULTICAST_Member *member,
@@ -552,10 +564,10 @@ GNUNET_MULTICAST_member_to_origin (struct GNUNET_MULTICAST_Member *member,
                                    void *cb_cls);
 
 
-/**
+/** 
  * Cancel request for message transmission to origin.
  *
- * @param rr request to cancel
+ * @param rr Request to cancel.
  */
 void
 GNUNET_MULTICAST_member_to_origin_cancel (struct GNUNET_MULTICAST_ResponseRequest *rr);
diff --git a/src/include/gnunet_psyc_service.h b/src/include/gnunet_psyc_service.h
index 8116e3d93..e2a839243 100644
--- a/src/include/gnunet_psyc_service.h
+++ b/src/include/gnunet_psyc_service.h
@@ -18,7 +18,7 @@
      Boston, MA 02111-1307, USA.
 */
 
-/**
+/** 
  * @file include/gnunet_psyc_service.h
  * @brief PSYC service; high-level access to the PSYC protocol
  *        note that clients of this API are NOT expected to
@@ -88,53 +88,53 @@ extern "C"
 #include "gnunet_multicast_service.h"
 
 
-/**
+/** 
  * Version number of GNUnet-PSYC API.
  */
 #define GNUNET_PSYC_VERSION 0x00000000
 
 
-/**
+/** 
  * Information flags for data fragments set via PSYC.
  */
 enum GNUNET_PSYC_FragmentStatus
 {
-  /**
+  /** 
    * This is the first part of data for the given method call.
    */
   GNUNET_PSYC_FS_FIRST = 1,
   
-  /**
+  /** 
    * This is the last part of data for the given method call.
    */
   GNUNET_PSYC_FS_LAST = 2,
 
-  /**
+  /** 
    * OR'ed flags if payload is not fragmented.
    */
   GNUNET_PSYC_FS_NOT_FRAGMENTED = (GNUNET_PSYC_FS_FIRST | GNUNET_PSYC_FS_LAST)
 };
 
 
-/**
+/** 
  * Method called from PSYC upon receiving a message indicating a call
- * to a 'method'.  
- *
- * @param cls closure
- * @param full_method_name original method name from PSYC (may be more
- *        specific than the registered method name due to try-and-slice matching)
- * @param sender who transmitted the message (origin, except for messages
- *        from one of the members to the origin)
- * @param message_id unique message counter for this message;
+ * to a @e method.  
+ *
+ * @param cls Closure.
+ * @param full_method_name Original method name from PSYC (may be more
+ *        specific than the registered method name due to try-and-slice matching).
+ * @param sender Who transmitted the message (origin, except for messages
+ *        from one of the members to the origin).
+ * @param message_id Unique message counter for this message;
  *                   (unique only in combination with the given sender for
- *                    this channel)
- * @param group_generation group generation counter for this message
+ *                    this channel).
+ * @param group_generation Group generation counter for this message
  *                   (always zero for messages from members to channel owner); FIXME: needed?
- * @param data_off byte offset of 'data' in the overall data of the method
- * @param data_size number of bytes in 'data'; 
- * @param data data stream given to the method (might not be zero-terminated 
- *             if data is binary)
- * @param frag fragmentation status for the data
+ * @param data_off Byte offset of @a data in the overall data of the method.
+ * @param data_size Number of bytes in @a data.
+ * @param data Data stream given to the method (might not be zero-terminated 
+ *             if data is binary).
+ * @param frag Fragmentation status for the data.
  */
 typedef int (*GNUNET_PSYC_Method)(void *cls,
                                   const char *full_method_name,
@@ -147,28 +147,28 @@ typedef int (*GNUNET_PSYC_Method)(void *cls,
                                   enum GNUNET_PSYC_FragmentStatus frag);
 
 
-/**
+/** 
  * Handle for the channel of a PSYC group.
  */
 struct GNUNET_PSYC_Channel;
 
 
-/**
- * Start a PSYC channel.  Will create a multicast group identified by
- * the given ECC key.  Messages recevied from group members will be
- * given to the respective handler methods.  If a new member wants to
- * join a group, the "join" method handler will be invoked; the join
- * handler must then generate a "join" message to approve the joining
- * of the new member.  The channel can also change group membership
- * without explicit requests.  Note that PSYC doesn't itself "understand"
- * join or leave messages, the respective methods must call other
- * PSYC functions to inform PSYC about the meaning of the respective
- * events.
- *
- * @param cfg configuration to use (to connect to PSYC service)
- * @param method functions to invoke on messages received from members,
- *                typcially at least contains functions for 'join' and 'leave'.
- * @param method_cls closure for 'method'
+/** 
+ * Create a PSYC channel.
+ *
+ * Will create a multicast group identified by the given ECC key.  Messages
+ * received from group members will be given to the respective handler methods.
+ * If a new member wants to join a group, the "join" method handler will be
+ * invoked; the join handler must then generate a "join" message to approve the
+ * joining of the new member.  The channel can also change group membership
+ * without explicit requests.  Note that PSYC doesn't itself "understand" join
+ * or leave messages, the respective methods must call other PSYC functions to
+ * inform PSYC about the meaning of the respective events.
+ *
+ * @param cfg Configuration to use (to connect to PSYC service).
+ * @param method Function to invoke on messages received from members,
+ *                typcially at least contains functions for @e join and @e leave.
+ * @param method_cls Closure for @a method.
  * @param priv_key ECC key that will be used to sign messages for this
  *                 PSYC session; public key is used to identify the
  *                 PSYC group; FIXME: we'll likely want to use
@@ -177,46 +177,46 @@ struct GNUNET_PSYC_Channel;
  *                 directly, but rather look it up in GADS for groups 
  *                 managed by other users, or select a file with the private
  *                 key(s) when setting up their own channels
- * @param join_policy what is the membership policy of the group?
+ * @param join_policy What is the membership policy of the group?
  *                 Used to automate group management decisions.
- * @return handle for the channel, NULL on error 
+ * @return Handle for the channel, NULL on error.
  */
 struct GNUNET_PSYC_Channel *
-GNUNET_PSYC_channel_start (const struct GNUNET_CONFIGURATION_Handle *cfg, 
-                           GNUNET_PSYC_Method method,
-                           void *method_cls,
-                           const struct GNUNET_CRYPTO_EccPrivateKey *priv_key,
-                           enum GNUNET_MULTICAST_JoinPolicy join_policy);
+GNUNET_PSYC_channel_create (const struct GNUNET_CONFIGURATION_Handle *cfg, 
+                            GNUNET_PSYC_Method method,
+                            void *method_cls,
+                            const struct GNUNET_CRYPTO_EccPrivateKey *priv_key,
+                            enum GNUNET_MULTICAST_JoinPolicy join_policy);
 
 
-/**
+/** 
  * Possible operations on PSYC state (persistent) and variables (per message).
  */
 enum GNUNET_PSYC_Operator
 {
-  /**
+  /** 
    * Replace the full state with the new value ("=").
    */
   GNUNET_PSYC_SOT_SET_STATE = 0,
   
-  /**
+  /** 
    * Delete the complete entry from the state (given data must be
-   * empty).  Equivalent to 'SET' with emtpy data, but more
+   * empty).  Equivalent to @a SET with empty data, but more
    * explicit ("=");
    */
   GNUNET_PSYC_SOT_DELETE = 0,
   
-  /**
+  /** 
    * Set the value of a variable to a new value (":").
    */
   GNUNET_PSYC_SOT_SET_VARIABLE,
   
-  /**
+  /** 
    * Add the given value to the set of values in the state ("+").
    */
   GNUNET_PSYC_SOT_ADD_STATE,
   
-  /**
+  /** 
    * Remove the given value from the set of values in the state ("-").
    */
   GNUNET_PSYC_SOT_REMOVE_STATE
@@ -224,23 +224,23 @@ enum GNUNET_PSYC_Operator
 };
 
 
-/**
- * Update channel state (or set a variable).  The state of a channel
- * must fit into the memory of each member (and the channel); large
- * values that require streaming must only be passed as the stream
- * arguments to methods.  State updates might not be transmitted to
- * group members until the next call to
- * 'GNUNET_PSYC_channel_notify_transmit_ready'.  Variable updates must
- * be given just before the call to the respective method that needs
- * the variables.
- *
- * @param channel handle to the PSYC group / channel
- * @param full_state_name name of the field in the channel state to change
- * @param type kind of update operation (add, remove, replace, delete)
- * @param data_size number of bytes in data
- * @param data new state value
- * @return GNUNET_OK on success, GNUNET_SYSERR on internal error
- *        (i.e. state too large)
+/** 
+ * Update channel state (or set a variable).
+ *
+ * The state of a channel must fit into the memory of each member (and the
+ * channel); large values that require streaming must only be passed as the
+ * stream arguments to methods.  State updates might not be transmitted to group
+ * members until the next call to GNUNET_PSYC_channel_notify_transmit_ready().
+ * Variable updates must be given just before the call to the respective method
+ * that needs the variables.
+ *
+ * @param channel Handle to the PSYC group / channel.
+ * @param full_state_name Name of the field in the channel state to change.
+ * @param type Kind of update operation (add, remove, replace, delete).
+ * @param data_size Number of bytes in data.
+ * @param data New state value.
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on internal error
+ *        (i.e. state too large).
  */
 int
 GNUNET_PSYC_channel_state_update (struct GNUNET_PSYC_Channel *channel,
@@ -250,24 +250,25 @@ GNUNET_PSYC_channel_state_update (struct GNUNET_PSYC_Channel *channel,
                                   const void *data);
 
 
-/**
- * Function called to provide data for a transmission via PSYC.  Note
- * that returning GNUNET_OK or GNUNET_SYSERR (but not GNUNET_NO)
+/** 
+ * Function called to provide data for a transmission via PSYC.
+ *
+ * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO)
  * invalidates the respective transmission handle.
  *
- * @param cls closure
- * @param message_id set to the unique message ID that was generated for
- *        this message
- * @param group_generation set to the group generation used for this
- *        message
- * @param data_size initially set to the number of bytes available in 'data',
- *        should be set to the number of bytes written to data (IN/OUT)
- * @param data where to write the body of the message to give to the method;
- *        function must copy at most '*data_size' bytes to 'data'.
- * @return GNUNET_SYSERR on error (fatal, aborts transmission)
- *         GNUNET_NO on success, if more data is to be transmitted later 
- *         (should be used if 'data_size' was not big enough to take all the data)
- *         GNUNET_YES if this completes the transmission (all data supplied)
+ * @param cls Closure.
+ * @param message_id Set to the unique message ID that was generated for
+ *        this message.
+ * @param group_generation Set to the group generation used for this
+ *        message.
+ * @param data_size[in,out] Initially set to the number of bytes available in @a data,
+ *        should be set to the number of bytes written to data (IN/OUT).
+ * @param data[out] Where to write the body of the message to give to the method;
+ *        function must copy at most @a *data_size bytes to @a data.
+ * @return #GNUNET_SYSERR on error (fatal, aborts transmission)
+ *         #GNUNET_NO on success, if more data is to be transmitted later 
+ *         (should be used if @a *data_size was not big enough to take all the data)
+ *         #GNUNET_YES if this completes the transmission (all data supplied)
  */
 typedef int (*GNUNET_PSYC_ChannelReadyNotify)(void *cls,
                                               uint64_t message_id,
@@ -276,22 +277,22 @@ typedef int (*GNUNET_PSYC_ChannelReadyNotify)(void *cls,
                                               void *data);
 
 
-/**
+/** 
  * Handle for a pending PSYC transmission operation.
  */
 struct GNUNET_PSYC_ChannelTransmitHandle;
 
 
-/**
+/** 
  * Send a message to call a method to all members in the PSYC channel.
  *
- * @param channel handle to the PSYC multicast group
- * @param increment_group_generation GNUNET_YES if we need to increment
- *        the group generation counter after transmitting this message
- * @param full_method_name which method should be invoked
- * @param notify function to call to obtain the arguments
- * @param notify_cls closure for 'notify'
- * @return transmission handle, NULL on error (i.e. more than one request queued)
+ * @param channel Handle to the PSYC multicast group.
+ * @param increment_group_generation #GNUNET_YES if we need to increment
+ *        the group generation counter after transmitting this message.
+ * @param full_method_name Which method should be invoked.
+ * @param notify Function to call to obtain the arguments.
+ * @param notify_cls Closure for @a notify.
+ * @return Transmission handle, NULL on error (i.e. more than one request queued).
  */
 struct GNUNET_PSYC_ChannelTransmitHandle *
 GNUNET_PSYC_channel_notify_transmit_ready (struct GNUNET_PSYC_Channel *channel,
@@ -301,69 +302,70 @@ GNUNET_PSYC_channel_notify_transmit_ready (struct GNUNET_PSYC_Channel *channel,
                                            void *notify_cls);
 
 
-/**
+/** 
  * Abort transmission request to channel.
  *
- * @param th handle of the request that is being aborted
+ * @param th Handle of the request that is being aborted.
  */
 void
 GNUNET_PSYC_channel_notify_transmit_ready_cancel (struct GNUNET_PSYC_ChannelTransmitHandle *th);
 
 
-/**
- * End a PSYC channel.
+/** 
+ * Destroy a PSYC channel.
  *
- * @param channel PSYC channel to terminate
+ * @param channel PSYC channel to terminate.
  */
-void
-GNUNET_PSYC_channel_end (struct GNUNET_PSYC_Channel *channel);
+tvoid
+GNUNET_PSYC_channel_destroy (struct GNUNET_PSYC_Channel *channel);
 
 
-/**
+/** 
  * Handle to access PSYC group operations for all members.
  */
 struct GNUNET_PSYC_Group;
 
 
-/**
- * Convert 'channel' to a 'group' handle to access the 'group' APIs.
+/** 
+ * Convert @a channel to a @e group handle to access the @e group APIs.
  * 
- * @param channel channel handle
- * @return group handle, valid for as long as 'channel' is valid
+ * @param channel Channel handle.
+ * @return Group handle, valid for as long as @a channel is valid.
  */ 
 struct GNUNET_PSYC_Group *
 GNUNET_PSYC_channel_get_group (struct GNUNET_PSYC_Channel *channel);
 
 
-/**
- * Convert 'member' to a 'group' handle to access the 'group' APIs.
+/** 
+ * Convert @a member to a @e group handle to access the @e group APIs.
  * 
- * @param member membership handle
- * @return group handle, valid for as long as 'member' is valid
+ * @param member Membership handle.
+ * @return Group handle, valid for as long as @a member is valid.
  */ 
 struct GNUNET_PSYC_Group *
 GNUNET_PSYC_member_get_group (struct GNUNET_PSYC_Member *member);
 
 
-/**
- * Add a member to the group.    Note that this will NOT generate any
- * PSYC traffic, it will merely update the local data base to modify
- * how we react to 'membership test' queries.  The channel still needs to
- * explicitly transmit a 'join' message to notify other group members
- * and they then also must still call this function in their respective
- * methods handling the 'join' message.  This way, how 'join' and 'leave'
- * operations are exactly implemented is still up to the application;
- * for example, there might be a 'leave_all' method to kick out everyone.
+/** 
+ * Add a member to the group.
+ *
+ * Note that this will NOT generate any PSYC traffic, it will merely update the
+ * local data base to modify how we react to <em>membership test</em> queries.  The
+ * channel still needs to explicitly transmit a @e join message to notify other
+ * group members and they then also must still call this function in their
+ * respective methods handling the @e join message.  This way, how @e join and
+ * @e leave operations are exactly implemented is still up to the application;
+ * for example, there might be a @e leave_all method to kick out everyone.
  *
  * Note that group members are explicitly trusted to execute such 
  * methods correctly; not doing so correctly will result in either
  * denying members access or offering access to group data to
  * non-members.
  *
- * @param group group handle
- * @param member which peer to add
- * @param message_id message ID for the message that changed the membership
- * @param group_generation the generation ID where the change went into effect
+ * @param group Group handle.
+ * @param member Which peer to add.
+ * @param message_id Message ID for the message that changed the membership.
+ * @param group_generation The generation ID where the change went into effect.
  */
 void
 GNUNET_PSYC_group_member_add (struct GNUNET_PSYC_Group *group,
@@ -372,25 +374,26 @@ GNUNET_PSYC_group_member_add (struct GNUNET_PSYC_Group *group,
                               uint64_t group_generation);
 
 
-/**
- * Remove a member from the group.  Note that this will NOT generate any
- * PSYC traffic, it will merely update the local data base to modify
- * how we react to 'membership test' queries.  The channel still needs to
- * explicitly transmit a 'leave' message to notify other group members
- * and they then also must still call this function in their respective
- * methods handling the 'leave' message.  This way, how 'join' and 'leave'
- * operations are exactly implemented is still up to the application;
- * for example, there might be a 'leave_all' message to kick out everyone.
+/** 
+ * Remove a member from the group.
+ *
+ * Note that this will NOT generate any PSYC traffic, it will merely update the
+ * local data base to modify how we react to <em>membership test</em> queries.  The
+ * channel still needs to explicitly transmit a @e leave message to notify other
+ * group members and they then also must still call this function in their
+ * respective methods handling the @e leave message.  This way, how @e join and
+ * @e leave operations are exactly implemented is still up to the application;
+ * for example, there might be a @e leave_all message to kick out everyone.
  *
  * Note that group members are explicitly trusted to perform these
  * operations correctly; not doing so correctly will result in either
  * denying members access or offering access to group data to
  * non-members.
  *
- * @param group group handle
- * @param member which peer to remove
- * @param message_id message ID for the message that changed the membership
- * @param group_generation the generation ID where the change went into effect
+ * @param group Group handle.
+ * @param member Which peer to remove.
+ * @param message_id Message ID for the message that changed the membership.
+ * @param group_generation The generation ID where the change went into effect.
  */
 void
 GNUNET_PSYC_group_member_remove (struct GNUNET_PSYC_Group *group,
@@ -399,16 +402,16 @@ GNUNET_PSYC_group_member_remove (struct GNUNET_PSYC_Group *group,
                                  uint64_t group_generation);
 
 
-/**
- * Function called to inform a member about state changes for a
- * channel.  Note that (for sets) only the delta is communicated, not
- * the full state.
+/** 
+ * Function called to inform a member about state changes for a channel.
  *
- * @param cls closure
- * @param full_state_name full name of the state
- * @param type how to interpret the change
- * @param state_value information about the new state
- * @param state_value_size number of bytes in 'state_value'
+ * Note that (for sets) only the delta is communicated, not the full state.
+ *
+ * @param cls Closure.
+ * @param full_state_name Full name of the state.
+ * @param type How to interpret the change.
+ * @param state_value Information about the new state.
+ * @param state_value_size Number of bytes in @a state_value.
  */
 typedef void (*GNUNET_PSYC_StateCallback)(void *cls,
                                           const char *full_state_name,
@@ -417,48 +420,49 @@ typedef void (*GNUNET_PSYC_StateCallback)(void *cls,
                                           size_t state_value_size);
 
 
-/**
+/** 
  * Descriptor for an event handler handling PSYC state updates.
  */
 struct GNUNET_PSYC_StateHandler
 {
 
-  /**
-   * Name of the state this handler calls about, used in try-and-slice matching.
+  /** 
+   * Name of the state variable this handler calls about, used in try-and-slice matching.
    */
   const char *state_name;
 
-  /**
+  /** 
    * Function to call whenever the respective state changes.
    */
   GNUNET_PSYC_StateCallback event_handler;
 
-  /**
-   * Closure for the 'event_handler' function.
+  /** 
+   * Closure for the @a event_handler function.
    */
   void *event_handler_cls;
 
 };
 
 
-/**
- * Join a PSYC group.  The entity joining is always the local peer.
- * The user must immediately use the 'GNUNET_PSYC_member_send_to_host'
- * (and possibly 'GNUNET_PSYC_member_host_variable_set') functions to
- * transmit a 'join_msg' to the channel; if the join request succeeds,
- * the channel state (and 'recent' method calls) will be replayed to
- * the joining member.  There is no explicit notification on failure
- * (as the channel may simply take days to approve, and disapproval is
- * simply being ignored).
+/** 
+ * Join a PSYC group.
+ *
+ * The entity joining is always the local peer.  The user must immediately use
+ * the GNUNET_PSYC_member_send_to_host() (and possibly
+ * GNUNET_PSYC_member_host_variable_set()) functions to transmit a @e join_msg to
+ * the channel; if the join request succeeds, the channel state (and @e recent
+ * method calls) will be replayed to the joining member.  There is no explicit
+ * notification on failure (as the channel may simply take days to approve, and
+ * disapproval is simply being ignored).
  *
- * @param cfg configuration to use
+ * @param cfg Configuration to use.
  * @param pub_key ECC key that identifies the channel we wish to join
- * @param method function to invoke on messages received from the channel,
- *                typcially at least contains functions for 'join' and 'leave'.
- * @param method_cls closure for 'method'
- * @param state_count number of state handlers
- * @param state_handlers array of state event handlers
- * @return handle for the member, NULL on error 
+ * @param method Function to invoke on messages received from the channel,
+ *                typically at least contains functions for @e join and @e leave.
+ * @param method_cls Closure for @a method.
+ * @param state_count Number of @a state_handlers.
+ * @param state_handlers Array of state event handlers.
+ * @return Handle for the member, NULL on error.
  */
 struct GNUNET_PSYC_Member *
 GNUNET_PSYC_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg, 
@@ -469,10 +473,12 @@ GNUNET_PSYC_member_join (const struct GNUNET_CONFIGURATION_Handle *cfg,
                          struct GNUNET_PSYC_StateHandler *state_handlers);
 
 
-/**
- * Leave a multicast group.  Will terminate the connection to the PSYC
- * service.  Polite clients should first explicitly send a 'leave'
- * request (via 'GNUNET_PSYC_member_send_to_host').  
+/** 
+ * Leave a multicast group.
+ *
+ * Will terminate the connection to the PSYC service.  Polite clients should
+ * first explicitly send a @e leave request (via
+ * GNUNET_PSYC_member_send_to_host()).
  *
  * @param member membership handle
  */
@@ -480,40 +486,41 @@ void
 GNUNET_PSYC_member_leave (struct GNUNET_PSYC_Member *member);
 
 
-/**
+/** 
  * Function called to provide data for a transmission to the channel
- * owner (aka the 'host' of the channel).  Note that returning
- * GNUNET_OK or GNUNET_SYSERR (but not GNUNET_NO) invalidates the
- * respective transmission handle.
- *
- * @param cls closure
- * @param data_size initially set to the number of bytes available in 'data',
- *        should be set to the number of bytes written to data (IN/OUT)
- * @param data where to write the body of the message to give to the method;
- *        function must copy at most '*data_size' bytes to 'data'.
- * @return GNUNET_SYSERR on error (fatal, aborts transmission)
- *         GNUNET_NO on success, if more data is to be transmitted later
- *         GNUNET_YES if this completes the transmission (all data supplied)
+ * owner (aka the @e host of the channel).
+ *
+ * Note that returning #GNUNET_OK or #GNUNET_SYSERR (but not #GNUNET_NO)
+ * invalidates the respective transmission handle.
+ *
+ * @param cls Closure.
+ * @param data_size[in,out] Initially set to the number of bytes available in @a data,
+ *        should be set to the number of bytes written to data (IN/OUT).
+ * @param data[out] Where to write the body of the message to give to the method;
+ *        function must copy at most @a *data_size bytes to @a data.
+ * @return #GNUNET_SYSERR on error (fatal, aborts transmission).
+ *         #GNUNET_NO on success, if more data is to be transmitted later.
+ *         #GNUNET_YES if this completes the transmission (all data supplied).
  */
 typedef int (*GNUNET_PSYC_OriginReadyNotify)(void *cls,
                                              size_t *data_size,
                                              char *data);
 
 
-/**
+/** 
  * Handle for a pending PSYC transmission operation.
  */
 struct GNUNET_PSYC_OriginTransmitHandle;
 
 
-/**
+/** 
  * Request a message to be sent to the channel origin.
  *
- * @param member membership handle
- * @param method_name which (PSYC) method should be invoked (on host)
- * @param notify function to call when we are allowed to transmit (to get data)
- * @param notify_cls closure for 'notify'
- * @return transmission handle, NULL on error (i.e. more than one request queued)
+ * @param member Membership handle.
+ * @param method_name Which (PSYC) method should be invoked (on host).
+ * @param notify Function to call when we are allowed to transmit (to get data).
+ * @param notify_cls Closure for @a notify.
+ * @return Transmission handle, NULL on error (i.e. more than one request queued).
  */
 struct GNUNET_PSYC_OriginTransmitHandle *
 GNUNET_PSYC_member_send_to_origin (struct GNUNET_PSYC_Member *member,
@@ -522,17 +529,19 @@ GNUNET_PSYC_member_send_to_origin (struct GNUNET_PSYC_Member *member,
                                    void *notify_cls);
 
 
-/**
+/** 
  * Set a (temporary, ":") variable for the next message being transmitted
- * via 'GNUNET_PSYC_member_send_to_host'. If 'GNUNET_PSYC_member_send_to_host'
- * is called and then cancelled, all variables that were set using this
- * function will be unset (lost/forgotten).  To clear a variable state after
- * setting it, you can also call this function again with NULL/0 for the value.
+ * via GNUNET_PSYC_member_send_to_host().
  *
- * @param member membership handle
- * @param variable_name name of the variable to set
- * @param value value to set for the given variable
- * @param value_size number of bytes in 'value'
+ * If GNUNET_PSYC_member_send_to_host() is called and then cancelled, all
+ * variables that were set using this function will be unset (lost/forgotten).
+ * To clear a variable state after setting it, you can also call this function
+ * again with NULL/0 for the @a value.
+ *
+ * @param member Membership handle.
+ * @param variable_name Name of the variable to set.
+ * @param value Value to set for the given variable.
+ * @param value_size Number of bytes in @a value.
  */
 uint64_t
 GNUNET_PSYC_member_origin_variable_set (struct GNUNET_PSYC_Member *member,
@@ -541,40 +550,40 @@ GNUNET_PSYC_member_origin_variable_set (struct GNUNET_PSYC_Member *member,
                                         size_t value_size);
 
 
-/**
+/** 
  * Abort transmission request to origin.
  *
- * @param th handle of the request that is being aborted
+ * @param th Handle of the request that is being aborted.
  */
 void
 GNUNET_PSYC_member_send_to_origin_cancel (struct GNUNET_PSYC_OriginTransmitHandle *th);
 
 
-/**
+/** 
  * Handle to a story telling operation.
  */
 struct GNUNET_PSYC_Story;
 
 
-/**
- * Request to be told the message history of the channel.  Historic
- * messages (but NOT the state at the time) will be replayed (given to
- * the normal method handlers) if available and if access is
- * permitted.
+/** 
+ * Request to be told the message history of the channel.
  *
- * @param member which channel should be replayed?
- * @param start earliest interesting point in history
- * @param end last (exclusive) interesting point in history
- * @param method function to invoke on messages received from the story
- * @param method_cls closure for 'method'
- * @param finish_cb function to call when the requested story has been fully 
+ * Historic messages (but NOT the state at the time) will be replayed (given to
+ * the normal method handlers) if available and if access is permitted.
+ *
+ * @param member Which channel should be replayed?
+ * @param start Earliest interesting point in history.
+ * @param end Last (exclusive) interesting point in history.
+ * @param method Function to invoke on messages received from the story.
+ * @param method_cls Closure for @a method.
+ * @param finish_cb Function to call when the requested story has been fully 
  *        told (counting message IDs might not suffice, as some messages
  *        might be secret and thus the listener would not know the story is 
  *        finished without being told explicitly); once this function
  *        has been called, the client must not call
- *        'GNUNET_PSYC_member_story_tell_cancel' anymore
- * @param finish_cb_cls closure to finish_cb
- * @return handle to cancel story telling operation
+ *        GNUNET_PSYC_member_story_tell_cancel() anymore.
+ * @param finish_cb_cls Closure to finish_cb.
+ * @return Handle to cancel story telling operation.
  */
 struct GNUNET_PSYC_Story *
 GNUNET_PSYC_member_story_tell (struct GNUNET_PSYC_Member *member,
@@ -586,35 +595,37 @@ GNUNET_PSYC_member_story_tell (struct GNUNET_PSYC_Member *member,
                                void *finish_cb_cls);
 
 
-/**
- * Abort story telling.  This function must not be called from within
- * method handlers (as given to 'GNUNET_PSYC_member_join') of the
- * member.
+/** 
+ * Abort story telling.
+ *
+ * This function must not be called from within method handlers (as given to
+ * GNUNET_PSYC_member_join()) of the member.
  *
- * @param story story telling operation to stop
+ * @param story Story telling operation to stop.
  */
 void
 GNUNET_PSYC_member_story_tell_cancel (struct GNUNET_PSYC_Story *story);
 
 
-/**
- * Call the given callback on all matching values (including
- * variables) in the channel state.  The callback is invoked
- * synchronously on all matching states (as the state is fully
- * replicated in the library in this process; channel states should be
+/** 
+ * Call the given callback on all matching values (including variables) in the
+ * channel state.
+ *
+ * The callback is invoked synchronously on all matching states (as the state is
+ * fully replicated in the library in this process; channel states should be
  * small, large data is to be passed as streaming data to methods).
  *
- * A name matches if it includes the 'state_name' prefix, thus
- * requesting the empty state ("") will match all values; requesting
- * "a_b" will also return values stored under "a_b_c".
+ * A name matches if it includes the @a state_name prefix, thus requesting the
+ * empty state ("") will match all values; requesting "a_b" will also return
+ * values stored under "a_b_c".
  *
- * @param member membership handle
- * @param state_name name of the state to query (full name 
- *        might be longer, this is only the prefix that must match)
- * @param cb function to call on the matching state values
- * @param cb_cls closure for 'cb'
- * @return message ID for which the state was returned (last seen
- *         message ID)
+ * @param member Membership handle.
+ * @param state_name Name of the state to query (full name 
+ *        might be longer, this is only the prefix that must match).
+ * @param cb Function to call on the matching state values.
+ * @param cb_cls Closure for @a cb.
+ * @return Message ID for which the state was returned (last seen
+ *         message ID).
  */
 uint64_t
 GNUNET_PSYC_member_state_get_all (struct GNUNET_PSYC_Member *member,
@@ -623,23 +634,24 @@ GNUNET_PSYC_member_state_get_all (struct GNUNET_PSYC_Member *member,
                                   void *cb_cls);
 
 
-/**
+/** 
  * Obtain the current value of the best-matching value in the state
- * (including variables).  Note that variables are only valid during a
- * GNUNET_PSYC_Method invocation, as variables are only valid for the
- * duration of a method invocation.  
+ * (including variables).
+ *
+ * Note that variables are only valid during a #GNUNET_PSYC_Method invocation, as
+ * variables are only valid for the duration of a method invocation.
  *
  * If the requested variable name does not have an exact state in
  * the state, the nearest less-specific name is matched; for example,
  * requesting "a_b" will match "a" if "a_b" does not exist.
  *
- * @param member membership handle
- * @param variable_name name of the variable to query 
- * @param return_value_size set to number of bytes in variable, 
+ * @param member Membership handle.
+ * @param variable_name Name of the variable to query.
+ * @param return_value_size Set to number of bytes in variable, 
  *        needed as variables might contain binary data and
- *        might also not be 0-terminated; set to 0 on errors
+ *        might also not be 0-terminated; set to 0 on errors.
  * @return NULL on error (no matching state or variable), pointer
-          to the respective value otherwise
+          to the respective value otherwise.
  */
 const void *
 GNUNET_PSYC_member_state_get (struct GNUNET_PSYC_Member *member,
diff --git a/src/include/gnunet_psycstore_service.h b/src/include/gnunet_psycstore_service.h
index 701f6940f..30671cda2 100644
--- a/src/include/gnunet_psycstore_service.h
+++ b/src/include/gnunet_psycstore_service.h
@@ -18,10 +18,10 @@
      Boston, MA 02111-1307, USA.
 */
 
-/**
+/** 
  * @file include/gnunet_psycstore_service.h
  * @brief PSYCstore service; implements persistent storage for the PSYC service
- * @author tg
+ * @author tg(x)
  * @author Christian Grothoff
  */
 #ifndef GNUNET_PSYCSTORE_SERVICE_H
@@ -37,18 +37,18 @@ extern "C"
 
 #include "gnunet_util_lib.h"
 
-/**
+/** 
  * Version number of GNUnet PSYCstore API.
  */
 #define GNUNET_PSYCSTORE_VERSION 0x00000000
 
-/**
+/** 
  * Handle for a PSYCstore
  */
 struct GNUNET_PSYCSTORE_Handle;
 
 
-/**
+/** 
  * Connect to the PSYCstore service.
  *
  * @param cfg Configuration to use.
@@ -59,7 +59,7 @@ struct GNUNET_PSYCSTORE_Handle *
 GNUNET_PSYCSTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 
-/**
+/** 
  * Disconnect from the PSYCstore service.
  *
  * @param h Handle for the connection.
@@ -68,22 +68,23 @@ void
 GNUNET_PSYCSTORE_disconnect (struct GNUNET_PSYCSTORE_Handle *h);
 
 
-/**
+/** 
  * Handle for an operation on the PSYCSTORE (useful to cancel the operation).
  */
 struct GNUNET_PSYCSTORE_OperationHandle;
 
 
-/**
- *
- * @param result GNUNET_SYSERR on error,
- *        GNUNET_YES on success or if the peer was a member,
- *        GNUNET_NO if the peer was not a member
+/** 
+ * Function called with the result of an asynchronous operation.
+; * 
+ * @param result #GNUNET_SYSERR on error,
+ *        #GNUNET_YES on success or if the peer was a member,
+ *        #GNUNET_NO if the peer was not a member
  */
 typedef void (*GNUNET_PSYCSTORE_ContinuationCallback)(void *cls,
                                                       int result);
 
-/**
+/** 
  * Store join/leave events for a PSYC channel in order to be able to answer
  * membership test queries later.
  *
@@ -91,7 +92,7 @@ typedef void (*GNUNET_PSYCSTORE_ContinuationCallback)(void *cls,
  * @param channel_id ID of the channel where the event happened.
  * @param message_id ID of the message in which this event was announced.
  * @param peer Identity of joining/leaving peer.
- * @param did_join GNUNET_YES on join, GNUNET_NO on leave.
+ * @param did_join #GNUNET_YES on join, #GNUNET_NO on leave.
  * @param ccb Callback to call with the result of the storage operation.
  * @param ccb_cls Closure for the callback.
  *
@@ -107,11 +108,12 @@ GNUNET_PSYCSTORE_membership_store (struct GNUNET_PSYCSTORE_Handle *h,
                                    void *ccb_cls);
 
 
-/**
+/** 
  * Test if a peer was a member of the channel when the message with the
- * specified ID was sent to the channel. This is useful in case of
- * retransmissions to check if the peer was authorized to see the requested
- * message.
+ * specified ID was sent to the channel.
+ *
+ * This is useful in case of retransmissions to check if the peer was authorized
+ * to see the requested message.
  *
  * @param h Handle for the PSYCstore.
  * @param channel_id The channel we are interested in.
@@ -121,7 +123,8 @@ GNUNET_PSYCSTORE_membership_store (struct GNUNET_PSYCSTORE_Handle *h,
  * @param ccb_cls Closure for the callback.
  *
  * @return Operation handle that can be used to cancel the operation.
- */struct GNUNET_PSYCSTORE_OperationHandle *
+ */
+struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_membership_test (struct GNUNET_PSYCSTORE_Handle *h,
                                   const struct GNUNET_HashCode *channel_id,
                                   uint64_t message_id,
@@ -130,6 +133,17 @@ GNUNET_PSYCSTORE_membership_test (struct GNUNET_PSYCSTORE_Handle *h,
                                   void *ccb_cls);
 
 
+/** 
+ * Store a message sent to a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel the message belongs to.
+ * @param message_id Message ID to store.
+ * @param ccb Callback to call with the result of the operation.
+ * @param ccb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_message_store (struct GNUNET_PSYCSTORE_Handle *h,
                                 const struct GNUNET_HashCode *channel_id,
@@ -138,11 +152,29 @@ GNUNET_PSYCSTORE_message_store (struct GNUNET_PSYCSTORE_Handle *h,
                                 void *ccb_cls);
 
 
+/** 
+ * Function called with the result of a GNUNET_PSYCSTORE_message_get() call.
+ *
+ * @param cls Closure.
+ * @param message_id ID of the message.
+ * @param message The retrieved message.
+ */
 typedef void (*GNUNET_PSYCSTORE_MessageResultCallback)(void *cls,       
                                                        uint64_t message_id,                                    
                                                        const struct GNUNET_MULTICAST_MessageHeader *message);
 
 
+/** 
+ * Retrieve a message by ID.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param message_id Message ID to check.
+ * @param rcb Callback to call with the result of the operation.
+ * @param rcb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_message_get (struct GNUNET_PSYCSTORE_Handle *h,
                               const struct GNUNET_HashCode *channel_id,
@@ -151,6 +183,16 @@ GNUNET_PSYCSTORE_message_get (struct GNUNET_PSYCSTORE_Handle *h,
                               void *rcb_cls);
 
 
+/** 
+ * Get latest message sent to a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param rcb Callback to call with the result of the operation.
+ * @param rcb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_message_get_latest (struct GNUNET_PSYCSTORE_Handle *h,
                                      const struct GNUNET_HashCode *channel_id,
@@ -158,30 +200,73 @@ GNUNET_PSYCSTORE_message_get_latest (struct GNUNET_PSYCSTORE_Handle *h,
                                      void *rcb_cls);
 
 
+/** 
+ * Store a state variable.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param name Name of variable.
+ * @param size Size of @a value.
+ * @param value Value of variable.
+ * @param ccb Callback to call with the result of the operation.
+ * @param ccb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_state_set (struct GNUNET_PSYCSTORE_Handle *h,
                             const struct GNUNET_HashCode *channel_id,
-                            const char *state_name,
+                            const char *name,
                             size_t size,
                             const void *value,
                             GNUNET_PSYCSTORE_ContinuationCallback ccb,
                             void *ccb_cls);
 
 
+/** 
+ * Function called with the value of a state variable.
+ *
+ * @param cls Closure.
+ * @param name Name of variable.
+ * @param size Size of @a value.
+ * @param value Value of variable.
+t * 
+ */
 typedef void (*GNUNET_PSYCSTORE_StateResultCallback)(void *cls,
-                                                     const char *state_name,
+                                                     const char *name,
                                                      size_t size,
                                                      const void *value);
 
 
+/** 
+ * Retrieve the given state variable for a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param name Name of variable to get.
+ * @param rcb Callback to call with the result.
+ * @param rcb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_state_get (struct GNUNET_PSYCSTORE_Handle *h,
                             const struct GNUNET_HashCode *channel_id,
-                            const char *state_name,
+                            const char *name,
                             GNUNET_PSYCSTORE_StateResultCallback rcb,
                             void *rcb_cls);
 
 
+/** 
+ * Retrieve all state variables for a channel.
+ *
+ * @param h Handle for the PSYCstore.
+ * @param channel_id The channel we are interested in.
+ * @param rcb Callback to call with the result.
+ * @param rcb_cls Closure for the callback.
+ * 
+ * @return Handle that can be used to cancel the operation.
+ */
 struct GNUNET_PSYCSTORE_OperationHandle *
 GNUNET_PSYCSTORE_state_get_all (struct GNUNET_PSYCSTORE_Handle *h,
                                 const struct GNUNET_HashCode *channel_id,
@@ -189,6 +274,11 @@ GNUNET_PSYCSTORE_state_get_all (struct GNUNET_PSYCSTORE_Handle *h,
                                 void *rcb_cls);
 
 
+/** 
+ * Cancel an operation.
+ *
+ * @param oh Handle for the operation to cancel.
+ */
 void
 GNUNET_PSYCSTORE_operation_cancel (struct GNUNET_PSYCSTORE_OperationHandle *oh);
 
diff --git a/src/include/gnunet_social_service.h b/src/include/gnunet_social_service.h
index 3e550ab51..e3483ca74 100644
--- a/src/include/gnunet_social_service.h
+++ b/src/include/gnunet_social_service.h
@@ -21,7 +21,7 @@
 /** 
  * @file include/gnunet_social_service.h
  * @brief Social service; implements social functionality using the PSYC service.
- * @author tg
+ * @author tg(x)
  * @author Christian Grothoff
  */
 #ifndef GNUNET_SOCIAL_SERVICE_H
@@ -74,7 +74,7 @@ struct GNUNET_SOCIAL_Slicer;
 
 /** 
  * Method called from SOCIAL upon receiving a message indicating a call
- * to a 'method'.
+ * to a @a method.
  *
  * @param cls Closure.
  * @param full_method_name Original method name from PSYC (may be more
@@ -83,11 +83,11 @@ struct GNUNET_SOCIAL_Slicer;
  * @param message_id Unique message counter for this message
  *                   (unique only in combination with the given sender for
  *                    this channel).
- * @param data_off Byte offset of 'data' in the overall data of the method.
- * @param data_size Number of bytes in 'data'.
- * @param data data stream given to the method (might not be zero-terminated 
- *             if data is binary)
- * @param frag fragmentation status for the data
+ * @param data_off Byte offset of @a data in the overall data of the method.
+ * @param data_size Number of bytes in @a data.
+ * @param data Data stream given to the method (might not be zero-terminated 
+ *             if data is binary).
+ * @param frag Fragmentation status for the data.
  */
 typedef int (*GNUNET_SOCIAL_Method)(void *cls,
                                     const char *full_method_name,
@@ -142,9 +142,9 @@ GNUNET_SOCIAL_slicer_destroy (struct GNUNET_SOCIAL_Slicer *slicer);
  * Create an ego using the private key from the given file.  If the file does
  * not exist, a fresh key is created.
  *
- * @param keyfile name of the file with the private key for the ego,
- *                NULL for ephemeral egos
- * @return handle to the ego, NULL on error
+ * @param keyfile Name of the file with the private key for the ego,
+ *                NULL for ephemeral egos.
+ * @return Handle to the ego, NULL on error.
  */
 struct GNUNET_SOCIAL_Ego *
 GNUNET_SOCIAL_ego_create (const char *keyfile);
@@ -153,7 +153,7 @@ GNUNET_SOCIAL_ego_create (const char *keyfile);
 /** 
  * Destroy a handle to an ego.
  *
- * @param ego ego to destroy
+ * @param ego Ego to destroy.
  */
 void
 GNUNET_SOCIAL_ego_destroy (struct GNUNET_SOCIAL_Ego *ego);
@@ -162,16 +162,16 @@ GNUNET_SOCIAL_ego_destroy (struct GNUNET_SOCIAL_Ego *ego);
 /** 
  * Function called asking for nym to be admitted to the place.
  *
- * Should call either 'GNUNET_SOCIAL_home_admit' or
- * 'GNUNET_SOCIAL_home_reject_entry' (possibly asynchronously).  If this owner
+ * Should call either GNUNET_SOCIAL_home_admit() or
+ * GNUNET_SOCIAL_home_reject_entry() (possibly asynchronously).  If this owner
  * cannot decide, it is fine to call neither function, in which case hopefully
- * some other owner of the home exists that will make the decision. The 'nym'
- * reference remains valid until the 'GNUNET_SOCIAL_FarewellCallback' is invoked
+ * some other owner of the home exists that will make the decision. The @a nym
+ * reference remains valid until the #GNUNET_SOCIAL_FarewellCallback is invoked
  * for it.
  *
  * @param cls Closure.
  * @param nym Handle for the user who wants to join.
- * @param join_msg_size Number of bytes in 'join_msg'.
+ * @param join_msg_size Number of bytes in @a join_msg.
  * @param join_msg Payload given on join (e.g. a password).
  */
 typedef void (*GNUNET_SOCIAL_AnswerDoorCallback)(void *cls,
@@ -181,10 +181,10 @@ typedef void (*GNUNET_SOCIAL_AnswerDoorCallback)(void *cls,
 
 
 /** 
- * Function called when a 'nym' leaves the place.
+ * Function called when a @a nym leaves the place.
  * 
- * This is also called if the 'nym' was never given permission to enter
- * (i.e. the 'nym' stopped asking to get in).
+ * This is also called if the @a nym was never given permission to enter
+ * (i.e. the @a nym stopped asking to get in).
  *
  * @param cls Closure.
  * @param nym Handle for the user who left.
@@ -197,8 +197,8 @@ typedef void (*GNUNET_SOCIAL_FarewellCallback)(void *cls,
  * Enter a home where guests (nyms) can be hosted.
  *
  * A home is created upon first entering, and exists until
- * 'GNUNET_SOCIAL_home_destroy' is called. It can also be left temporarily using
- * 'GNUNET_SOCIAL_home_leave'.
+ * GNUNET_SOCIAL_home_destroy() is called. It can also be left temporarily using
+ * GNUNET_SOCIAL_home_leave().
  *
  * @param cfg Configuration to contact the social service.
  * @param home_keyfile File with the private key for the home,
@@ -209,7 +209,7 @@ typedef void (*GNUNET_SOCIAL_FarewellCallback)(void *cls,
  * @param slicer Slicer to handle guests talking.
  * @param listener_cb Function to handle new nyms that want to join.
  * @param farewell_cb Function to handle departing nyms.
- * @param cls Closure for 'listener_cb' and 'farewell_cb'.
+ * @param cls Closure for @a listener_cb and @a farewell_cb.
  * @return Handle for a new home.
  */
 struct GNUNET_SOCIAL_Home *
@@ -224,12 +224,12 @@ GNUNET_SOCIAL_home_enter (const struct GNUNET_CONFIGURATION_Handle *cfg,
 
 
 /** 
- * Admit 'nym' to the 'home'.
+ * Admit @a nym to the @a home.
  *
- * The 'nym' reference will remain valid until either the home is destroyed or
- * 'nym' leaves.
+ * The @a nym reference will remain valid until either the home is destroyed or
+ * @a nym leaves.
  *
- * @param home Home to allow 'nym' to join.
+ * @param home Home to allow @a nym to join.
  * @param nym Handle for the entity that wants to join.
  */
 void
@@ -238,10 +238,10 @@ GNUNET_SOCIAL_home_admit (struct GNUNET_SOCIAL_Home *home,
 
 
 /** 
- * Throw 'nym' out of the 'home'.
+ * Throw @a nym out of the @a home.
  *
- * The 'nym' reference will remain valid until the
- * 'GNUNET_SOCIAL_FarewellCallback' is invoked,
+ * The @a nym reference will remain valid until the
+ * #GNUNET_SOCIAL_FarewellCallback is invoked,
  * which should be very soon after this call.
  *
  * @param home Home to eject nym from.
@@ -253,12 +253,12 @@ GNUNET_SOCIAL_home_eject (struct GNUNET_SOCIAL_Home *home,
 
 
 /** 
- * Refuse 'nym' entry into the 'home'.
+ * Refuse @a nym entry into the @a home.
  *
- * @param home Home to disallow 'nym' to join.
+ * @param home Home to disallow @a nym to join.
  * @param nym Handle for the entity that wanted to join.
  * @param method Method name to invoke on caller.
- * @param message_size Number of bytes in 'message' for method.
+ * @param message_size Number of bytes in @a message for method.
  * @param message Rejection message to send back.
  *
  * FIXME: allow setting variables as well for the message
@@ -274,7 +274,7 @@ GNUNET_SOCIAL_home_reject_entry (struct GNUNET_SOCIAL_Home *home,
 /** 
  * Get the identity of a user.
  *
- * Suitable, for example, to be used with 'GNUNET_NAMESTORE_zone_to_name'.
+ * Suitable, for example, to be used with GNUNET_NAMESTORE_zone_to_name().
  *
  * @param nym Pseudonym to map to a cryptographic identifier.
  * @param identity Set to the identity of the nym (short hash of the public key).
@@ -299,13 +299,13 @@ GNUNET_SOCIAL_home_get_address (struct GNUNET_SOCIAL_Home *home,
 /** 
  * (Re)decorate the home by changing objects in it.
  *
- * If the operation is 'GNUNET_PSYC_SOT_SET_VARIABLE' then the decoration only
+ * If the operation is #GNUNET_PSYC_SOT_SET_VARIABLE then the decoration only
  * applies to the next announcement by the home owner.
  *
  * @param home The home to decorate.
  * @param operation Operation to perform on the object.
  * @param object_name Name of the object to modify.
- * @param object_value_size Size of the given 'object_value'.
+ * @param object_value_size Size of the given @a object_value.
  * @param object_value Value to use for the modification.
  */
 void
@@ -330,7 +330,7 @@ struct GNUNET_SOCIAL_Announcement;
  * @param home Home to address the announcement to.
  * @param full_method_name Method to use for the announcement.
  * @param notify Function to call to get the payload of the announcement.
- * @param notify_cls Closure for 'notify'.
+ * @param notify_cls Closure for @a notify.
  * @return NULL on error (announcement already in progress?).
  */
 struct GNUNET_SOCIAL_Announcement *
@@ -353,8 +353,8 @@ GNUNET_SOCIAL_home_announce_cancel (struct GNUNET_SOCIAL_Announcement *a);
  * Convert our home to a place so we can access it via the place API.
  *
  * @param home Handle for the home.
- * @return Place handle for the same home, valid as long as 'home' is valid;
- *         do NOT try to 'GNUNET_SOCIAL_place_leave' this place, it's your home!m
+ * @return Place handle for the same home, valid as long as @a home is valid;
+ *         do NOT try to GNUNET_SOCIAL_place_leave() this place, it's your home!
  */
 struct GNUNET_SOCIAL_Place *
 GNUNET_SOCIAL_home_to_place (struct GNUNET_SOCIAL_Home *home);
@@ -392,7 +392,7 @@ GNUNET_SOCIAL_home_destroy (struct GNUNET_SOCIAL_Home *home);
  *        key already; 'HEX.zkey' however would refer to
  *        the 'PLACE' record in the GADS zone with the public key
  *        'HEX'.
- * @param join_msg_size Number of bytes in 'join_msg'.
+ * @param join_msg_size Number of bytes in @a join_msg.
  * @param join_msg Message to give to the join callback.
  * @return NULL on errors, otherwise handle to the place.
  */
@@ -411,11 +411,11 @@ struct GNUNET_SOCIAL_WatchHandle;
  * Watch a place for changed objects.
  *
  * @param place Place to watch.
- * @param object_filter Object prefix to match. if 
- * @param state_cb 
- * @param state_cb_cls 
+ * @param object_filter Object prefix to match.
+ * @param state_cb Function to call when an object/state changes.
+ * @param state_cb_cls Closure for callback.
  * 
- * @return 
+ * @return Handle that can be used to cancel watching.
  */
 struct GNUNET_SOCIAL_WatchHandle *
 GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
@@ -424,6 +424,11 @@ GNUNET_SOCIAL_place_watch (struct GNUNET_SOCIAL_Place *place,
                            void *state_cb_cls);
 
 
+/** 
+ * Cancel watching a place for changed objects.
+ *
+ * @param wh Watch handle to cancel.
+ */
 void
 GNUNET_SOCIAL_place_watch_cancel (struct GNUNET_SOCIAL_WatchHandle *wh);
 
@@ -464,6 +469,8 @@ GNUNET_SOCIAL_place_look_for (struct GNUNET_SOCIAL_Place *place,
 
 /** 
  * Stop looking at objects.
+ *
+ * @param lh Look handle to stop.
  */
 void
 GNUNET_SOCIAL_place_look_cancel (struct GNUNET_SOCIAL_LookHandle *lh);
@@ -492,7 +499,7 @@ GNUNET_SOCIAL_place_look_at (struct GNUNET_SOCIAL_Place *place,
  *
  * @param place Place to talk in.
  * @param variable_name Name of variable to set.
- * @param value_size Number of bytes in 'value'.
+ * @param value_size Number of bytes in @a value.
  * @param value Value of variable.
  */
 void
@@ -514,7 +521,7 @@ struct GNUNET_SOCIAL_TalkRequest;
  * @param place Place where we want to talk to the host.
  * @param method_name Method to invoke on the host.
  * @param cb Function to use to get the payload for the method.
- * @param cb_cls Closure for 'cb'.
+ * @param cb_cls Closure for @a cb.
  * @return NULL if we are already trying to talk to the host,
  *         otherwise handle to cancel the request.
  */
@@ -530,9 +537,9 @@ GNUNET_SOCIAL_place_talk (struct GNUNET_SOCIAL_Place *place,
  * FIXME: look up nym in GADS and talk to its place.
  *
  * @param nym Nym we want to talk to.
- * @param method_name Method to invoke on the nym.
+ * @param method_name Method to invoke on the @a nym.
  * @param cb Function to use to get the payload for the method.
- * @param cb_cls Closure for 'cb'.
+ * @param cb_cls Closure for @a cb.
  * @return NULL if we are already trying to talk to the host,
  *         otherwise handle to cancel the request.
  */
@@ -593,13 +600,13 @@ GNUNET_SOCIAL_place_get_history_cancel (struct GNUNET_SOCIAL_HistoryLesson *hist
 /** 
  * Leave a place (destroys the place handle).
  * 
- * Can either move our user into an 'away' state (in which we continue to record
+ * Can either move our user into an @e away state (in which we continue to record
  * ongoing conversations and state changes if our peer is running), or leave the
  * place entirely and stop following the conversation.
  *
  * @param place Place to leave.
- * @param keep_following GNUNET_YES to ask the social service to continue
- *        to follow the conversation, GNUNET_NO to fully leave the place.
+ * @param keep_following #GNUNET_YES to ask the social service to continue
+ *        to follow the conversation, #GNUNET_NO to fully leave the place.
  */
 void
 GNUNET_SOCIAL_place_leave (struct GNUNET_SOCIAL_Place *place,