docs: Add various missing documentation comments and update sections.txt

This straightens out the last few bits of the documentation and almost
allows `make check` to pass in docs/.

7 files changed, 173 insertions, 4 deletions

diff --git a/agent/address.h b/agent/address.h
index 9e91248..603afe2 100644
--- a/agent/address.h
+++ b/agent/address.h
@@ -67,9 +67,6 @@ G_BEGIN_DECLS
 
 /**
  * NiceAddress:
- * @addr: Generic sockaddr address
- * @ip4: IPv4 sockaddr address
- * @ip6: IPv6 sockaddr address
  *
  * The #NiceAddress structure that represents an IPv4 or IPv6 address.
  */
diff --git a/docs/reference/libnice/libnice-sections.txt b/docs/reference/libnice/libnice-sections.txt
index dd185f0..5c27fac 100644
--- a/docs/reference/libnice/libnice-sections.txt
+++ b/docs/reference/libnice/libnice-sections.txt
@@ -49,6 +49,7 @@ nice_agent_parse_remote_stream_sdp
 nice_agent_parse_remote_candidate_sdp
 nice_agent_get_io_stream
 nice_agent_get_selected_socket
+nice_agent_get_component_state
 nice_component_state_to_string
 <SUBSECTION Standard>
 NICE_AGENT
@@ -139,6 +140,7 @@ StunAgentUsageFlags
 StunValidationStatus
 StunMessageIntegrityValidate
 StunDefaultValidaterData
+StunDebugHandler
 stun_agent_init
 stun_agent_validate
 stun_agent_default_validater
@@ -152,8 +154,12 @@ stun_agent_forget_transaction
 stun_agent_set_software
 stun_debug_enable
 stun_debug_disable
+stun_set_debug_handler
 <SUBSECTION Private>
 StunAgentSavedIds
+stun_debug
+stun_debug_bytes
+stun_agent_t
 </SECTION>
 
 
@@ -266,6 +272,8 @@ stun_timer_start
 stun_timer_start_reliable
 stun_timer_refresh
 stun_timer_remainder
+<SUBSECTION Private>
+stun_timer_s
 </SECTION>
 
 <SECTION>
diff --git a/stun/constants.h b/stun/constants.h
index aa06153..29e1cec 100644
--- a/stun/constants.h
+++ b/stun/constants.h
@@ -38,6 +38,107 @@
 #define _STUN_CONSTANTS_H
 
 
+/**
+ * SECTION:stunconstants
+ * @short_description: STUN constants
+ * @include: stun/constants.h
+ * @stability: Stable
+ *
+ * Various constants defining parts of the STUN and TURN protocols and
+ * on-the-wire packet formats.
+ */
+
+/**
+ * STUN_ATTRIBUTE_LENGTH_LEN:
+ *
+ * Length of the length field of a STUN attribute (in bytes).
+ */
+/**
+ * STUN_ATTRIBUTE_LENGTH_POS:
+ *
+ * Offset of the length field of a STUN attribute (in bytes).
+ */
+/**
+ * STUN_ATTRIBUTE_TYPE_LEN:
+ *
+ * Length of the type field of a STUN attribute (in bytes).
+ */
+/**
+ * STUN_ATTRIBUTE_TYPE_POS:
+ *
+ * Offset of the type field of a STUN attribute (in bytes).
+ */
+/**
+ * STUN_ATTRIBUTE_VALUE_POS:
+ *
+ * Offset of the value field of a STUN attribute (in bytes).
+ */
+/**
+ * STUN_ID_LEN:
+ *
+ * Length of the ID field of a STUN message (in bytes).
+ */
+/**
+ * STUN_MAGIC_COOKIE:
+ *
+ * Magic cookie value used to identify STUN messages.
+ */
+/**
+ * TURN_MAGIC_COOKIE:
+ *
+ * Magic cookie value used to identify TURN messages.
+ */
+/**
+ * STUN_MAX_MESSAGE_SIZE_IPV4:
+ *
+ * Maximum size of a STUN message sent over IPv4 (in bytes).
+ */
+/**
+ * STUN_MAX_MESSAGE_SIZE_IPV6:
+ *
+ * Maximum size of a STUN message sent over IPv6 (in bytes).
+ */
+/**
+ * STUN_MESSAGE_ATTRIBUTES_POS:
+ *
+ * Offset of the attributes of a STUN message (in bytes).
+ */
+/**
+ * STUN_MESSAGE_HEADER_LENGTH:
+ *
+ * Total length of a STUN message header (in bytes).
+ */
+/**
+ * STUN_MESSAGE_LENGTH_LEN:
+ *
+ * Length of the length field of a STUN message (in bytes).
+ */
+/**
+ * STUN_MESSAGE_LENGTH_POS:
+ *
+ * Offset of the length field of a STUN message (in bytes).
+ */
+/**
+ * STUN_MESSAGE_TRANS_ID_LEN:
+ *
+ * Length of the transaction ID field of a STUN message (in bytes).
+ */
+/**
+ * STUN_MESSAGE_TRANS_ID_POS:
+ *
+ * Offset of the transaction ID field of a STUN message (in bytes).
+ */
+/**
+ * STUN_MESSAGE_TYPE_LEN:
+ *
+ * Length of the type field of a STUN message (in bytes).
+ */
+/**
+ * STUN_MESSAGE_TYPE_POS:
+ *
+ * Offset of the type field of a STUN message (in bytes).
+ */
+
 #define STUN_MESSAGE_TYPE_POS 0
 #define STUN_MESSAGE_TYPE_LEN 2
 #define STUN_MESSAGE_LENGTH_POS \
@@ -59,6 +160,11 @@
 #define STUN_ATTRIBUTE_VALUE_POS \
   (STUN_ATTRIBUTE_LENGTH_POS + STUN_ATTRIBUTE_LENGTH_LEN)
 
+/**
+ * STUN_ATTRIBUTE_HEADER_LENGTH:
+ *
+ * Length of a single STUN attribute header (in bytes).
+ */
 #define STUN_ATTRIBUTE_HEADER_LENGTH STUN_ATTRIBUTE_VALUE_POS
 
 
@@ -68,7 +174,19 @@
 
 #define STUN_ID_LEN 16
 
+/**
+ * STUN_AGENT_MAX_SAVED_IDS:
+ *
+ * Maximum number of simultaneously ongoing STUN transactions.
+ */
 #define STUN_AGENT_MAX_SAVED_IDS 200
+
+/**
+ * STUN_AGENT_MAX_UNKNOWN_ATTRIBUTES:
+ *
+ * Maximum number of unknown attribute which can be handled in a single STUN
+ * message.
+ */
 #define STUN_AGENT_MAX_UNKNOWN_ATTRIBUTES 256
 
 #define STUN_MAGIC_COOKIE 0x2112A442
diff --git a/stun/debug.h b/stun/debug.h
index 94498ff..d4884d5 100644
--- a/stun/debug.h
+++ b/stun/debug.h
@@ -59,8 +59,26 @@ void stun_debug_enable (void);
  */
 void stun_debug_disable (void);
 
+/**
+ * StunDebugHandler:
+ * @format: printf()-style debug message format string
+ * @ap: Parameters to substitute into message placeholders
+ *
+ * Callback for a debug message from the STUN code.
+ */
 typedef void (*StunDebugHandler) (const char *format, va_list ap);
 
+/**
+ * stun_set_debug_handler:
+ * @handler: (nullable): Handler for STUN debug messages, or %NULL to use the
+ *   default
+ *
+ * Set a callback function to be invoked for each debug message from the STUN
+ * code. The callback will only be invoked if STUN debugging is enabled using
+ * stun_debug_enable().
+ *
+ * The default callback prints the formatted debug message to stderr.
+ */
 void stun_set_debug_handler (StunDebugHandler handler);
 
 #if defined(__GNUC__) && (__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 4))
diff --git a/stun/stunmessage.h b/stun/stunmessage.h
index 75d2850..a57e170 100644
--- a/stun/stunmessage.h
+++ b/stun/stunmessage.h
@@ -163,6 +163,8 @@ typedef enum
  * TURN draft 09 and 12
  * @STUN_ATTRIBUTE_LIFETIME: The LIFETIME attribute as defined by TURN
  * draft 04, 09 and 12
+ * @STUN_ATTRIBUTE_MS_ALTERNATE_SERVER: The ALTERNATE-SERVER attribute as
+ * defined by [MS-TURN]
  * @STUN_ATTRIBUTE_MAGIC_COOKIE: The MAGIC-COOKIE attribute as defined by
  * the rosenberg-midcom TURN draft 08
  * @STUN_ATTRIBUTE_BANDWIDTH: The BANDWIDTH attribute as defined by TURN draft 04
diff --git a/stun/usages/timer.h b/stun/usages/timer.h
index e8f0786..e6501cb 100644
--- a/stun/usages/timer.h
+++ b/stun/usages/timer.h
@@ -200,6 +200,7 @@ void stun_timer_start (StunTimer *timer, unsigned int initial_timeout,
 /**
  * stun_timer_start_reliable:
  * @timer: The #StunTimer to start
+ * @initial_timeout: The initial timeout to use before the first retransmission
  *
  * Starts a STUN transaction retransmission timer for a reliable transport.
  * This should be called as soon as you send the message for the first time on
diff --git a/stun/usages/turn.h b/stun/usages/turn.h
index 388ec4f..7a2d4e6 100644
--- a/stun/usages/turn.h
+++ b/stun/usages/turn.h
@@ -96,6 +96,10 @@ typedef enum {
  * Google Talk's relay server
  * @STUN_USAGE_TURN_COMPATIBILITY_MSN: Use the specification compatible with
  * MSN TURN servers
+ * @STUN_USAGE_TURN_COMPATIBILITY_OC2007: Use the specification compatible with
+ * Microsoft Office Communicator 2007
+ * @STUN_USAGE_TURN_COMPATIBILITY_RFC5766: Use the specification compatible with
+ * RFC 5766 (the final, canonical TURN standard)
  *
  * Specifies which TURN specification compatibility to use
  */
@@ -205,7 +209,28 @@ size_t stun_usage_turn_create_refresh (StunAgent *agent, StunMessage *msg,
     uint8_t *password, size_t password_len,
     StunUsageTurnCompatibility compatibility);
 
-
+/**
+ * stun_usage_turn_create_permission:
+ * @agent: The #StunAgent to use to build the request
+ * @msg: The #StunMessage to build
+ * @buffer: The buffer to use for creating the #StunMessage
+ * @buffer_len: The size of the @buffer
+ * @username: The username to use in the request
+ * @username_len: The length of @username
+ * @password: The key to use for building the MESSAGE-INTEGRITY
+ * @password_len: The length of @password
+ * @realm: The realm identifier to use in the request
+ * @realm_len: The length of @realm
+ * @nonce: Unique and securely random nonce to use in the request
+ * @nonce_len: The length of @nonce
+ * @peer: Server-reflexive host address to request permission for
+ * @compatibility: The compatibility mode to use for building the
+ * CreatePermission request
+ *
+ * Create a new TURN CreatePermission request
+ *
+ * Returns: The length of the message to send
+ */
 size_t stun_usage_turn_create_permission (StunAgent *agent, StunMessage *msg,
     uint8_t *buffer, size_t buffer_len,
     uint8_t *username, size_t username_len,