1 files changed, 26 insertions, 9 deletions

diff --git a/toxcore/tox.api.h b/toxcore/tox.api.h
index 732262f1..39b457ea 100644
--- a/toxcore/tox.api.h
+++ b/toxcore/tox.api.h
@@ -2232,7 +2232,7 @@ namespace conference {
   /**
    * Creates a new conference.
    *
-   * This function creates a new text conference.
+   * This function creates and connects to a new text conference.
    *
    * @return conference number on success, or an unspecified value on failure.
    */
@@ -2279,7 +2279,10 @@ namespace conference {
   namespace peer {
 
     /**
-     * Return the number of peers in the conference. Return value is unspecified on failure.
+     * Return the number of online peers in the conference. The unsigned 
+     * integers less than this number are the valid values of peer_number for 
+     * the functions querying these peers. Return value is unspecified on 
+     * failure.
      */
     const uint32_t count(uint32_t conference_number)
         with error for peer_query;
@@ -2327,7 +2330,9 @@ namespace conference {
   namespace offline_peer {
 
     /**
-     * Return the number of offline peers in the conference. Return value is unspecified on failure.
+     * Return the number of offline peers in the conference. The unsigned 
+     * integers less than this number are the valid values of offline_peer_number for 
+     * the functions querying these peers. Return value is unspecified on failure.
      */
     const uint32_t count(uint32_t conference_number)
         with error for peer_query;
@@ -2388,10 +2393,6 @@ namespace conference {
   /**
    * Invites a friend to a conference.
    *
-   * We must be connected to the conference, meaning that the conference has not
-   * been deleted, and either we created the conference with the $new function,
-   * or a `${event connected}` event has occurred for the conference.
-   *
    * @param friend_number The friend number of the friend we want to invite.
    * @param conference_number The conference number of the conference we want to invite the friend to.
    *
@@ -2416,6 +2417,14 @@ namespace conference {
   /**
    * Joins a conference that the client has been invited to.
    *
+   * After successfully joining the conference, the client will not be "connected"
+   * to it until a handshaking procedure has been completed. A
+   * `${event connected}` event will then occur for the conference. The client
+   * will then remain connected to the conference until the conference is deleted,
+   * even across core restarts. Many operations on a conference will fail with a
+   * corresponding error if attempted on a conference to which the client is not
+   * yet connected.
+   *
    * @param friend_number The friend number of the friend who sent the invite.
    * @param cookie Received via the `${event invite}` event.
    * @param length The size of cookie.
@@ -2552,8 +2561,16 @@ namespace conference {
     size();
 
     /**
-     * Copy a list of valid conference IDs into the array chatlist. Determine how much space
-     * to allocate for the array with the `$size` function.
+     * Copy a list of valid conference numbers into the array chatlist. Determine
+     * how much space to allocate for the array with the `$size` function.
+     *
+     * Note that `${savedata.get}` saves all connected conferences;
+     * when toxcore is created from savedata in which conferences were saved, those
+     * conferences will be connected at startup, and will be listed by
+     * `$get`.
+     *
+     * The conference number of a loaded conference may differ from the conference
+     * number it had when it was saved.
      */
     get();
   }