[Pkg-telepathy-commits] [libnice] 147/265: agent: Expand documentation for a couple of NiceAgent functions

[Simon McVittie]

This is an automated email from the git hooks/post-receive script.

smcv pushed a commit to branch debian
in repository libnice.

commit 9c5f3010a61f3fe382cb5eed1c8b8af644e181da
Author: Philip Withnall <philip.withnall at collabora.co.uk>
Date:   Tue Feb 11 10:01:18 2014 +0000

    agent: Expand documentation for a couple of NiceAgent functions
    
    Expand documentation for nice_agent_gather_candidates() and
    nice_agent_set_remote_credentials().
---
 agent/agent.h | 36 ++++++++++++++++++++++--------------
 1 file changed, 22 insertions(+), 14 deletions(-)

diff --git a/agent/agent.h b/agent/agent.h
index 70fb7c6..588100e 100644
--- a/agent/agent.h
+++ b/agent/agent.h
@@ -496,17 +496,23 @@ gboolean nice_agent_set_relay_info(
 
 /**
  * nice_agent_gather_candidates:
- * @agent: The #NiceAgent Object
- * @stream_id: The id of the stream to start
+ * @agent: The #NiceAgent object
+ * @stream_id: The ID of the stream to start
+ *
+ * Allocate and start listening on local candidate ports and start the remote
+ * candidate gathering process.
+ * Once done, #NiceAgent::candidate-gathering-done is called for the stream.
+ * As soon as this function is called, #NiceAgent::new-candidate signals may be
+ * emitted, even before this function returns.
  *
- * Start the candidate gathering process.
- * Once done, #NiceAgent::candidate-gathering-done is called for the stream
+ * nice_agent_get_local_candidates() will only return non-empty results after
+ * calling this function.
  *
  * <para>See also: nice_agent_add_local_address()</para>
  * <para>See also: nice_agent_set_port_range()</para>
  *
- * Returns: %FALSE if the stream id is invalid or if a host candidate couldn't be allocated
- * on the requested interfaces/ports.
+ * Returns: %FALSE if the stream ID is invalid or if a host candidate couldn't
+ * be allocated on the requested interfaces/ports; %TRUE otherwise
  *
  <note>
    <para>
@@ -555,14 +561,16 @@ nice_agent_set_remote_credentials (
  * nice_agent_get_local_credentials:
  * @agent: The #NiceAgent Object
  * @stream_id: The ID of the stream
- * @ufrag: a pointer to a NULL-terminated string containing
- * an ICE username fragment [OUT].
- * This string must be freed with g_free()
- * @pwd: a pointer to a NULL-terminated string containing an ICE
- * password [OUT]
- * This string must be freed with g_free()
- *
- * Gets the local credentials for stream @stream_id.
+ * @ufrag: (out callee-allocates): return location for a nul-terminated string
+ * containing an ICE username fragment; must be freed with g_free()
+ * @pwd: (out callee-allocates): return location for a nul-terminated string
+ * containing an ICE password; must be freed with g_free()
+ *
+ * Gets the local credentials for stream @stream_id. This may be called any time
+ * after creating a stream using nice_agent_add_stream().
+ *
+ * An error will be returned if this is called for a non-existent stream, or if
+ * either of @ufrag or @pwd are %NULL.
  *
  * Returns: %TRUE on success, %FALSE on error.
  */

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-telepathy/libnice.git