Improve documentation

Signed-off-by: Steffen Jaeckel <jaeckel-floss@eyet-services.de>

README.markdown

@@ -88,7 +88,7 @@ or if you have everything configured properly:
 
 Then open `docs/html/index.html`.
 
-An online version of the documentation of the latest release is available on http://strophe.im/libstrophe/
+An online version of the documentation of the latest release is available on https://strophe.im/libstrophe/
 
 Releases
 --------

libstrophe.pc.in

@@ -5,7 +5,7 @@ includedir=@includedir@
 
 Name: libstrophe
 Description: A simple, lightweight C library for writing XMPP clients
-URL: http://strophe.im/libstrophe/
+URL: https://strophe.im/libstrophe/
 Version: @VERSION@
 Requires:
 Requires.private: @PC_REQUIRES@

src/auth.c

@@ -1102,10 +1102,10 @@ _handle_features_sasl(xmpp_conn_t *conn, xmpp_stanza_t *stanza, void *userdata)
 
     UNUSED(userdata);
 
-    /* remove missing features handler */
+    /* Remove missing features handler */
     xmpp_timed_handler_delete(conn, _handle_missing_features_sasl);
 
-    /* check whether resource binding is required */
+    /* Check whether resource binding is required */
     bind = xmpp_stanza_get_child_by_name(stanza, "bind");
     if (bind) {
         ns = xmpp_stanza_get_ns(bind);
@@ -1129,15 +1129,15 @@ _handle_features_sasl(xmpp_conn_t *conn, xmpp_stanza_t *stanza, void *userdata)
                 ns != NULL && strcmp(ns, XMPP_NS_SESSION) == 0;
     }
 
+    /* Check stream-management support */
     if (xmpp_stanza_get_child_by_name_and_ns(stanza, "sm", XMPP_NS_SM)) {
-        /* stream management supported */
         conn->sm_state->sm_support = 1;
     }
 
-    /* we are expecting either <bind/> and <session/> since this is a
+    /* We are expecting either <bind/> and optionally <session/> since this is a
        XMPP style connection or we <resume/> the previous session */
 
-    /* check whether we can <resume/> the previous session */
+    /* Check whether we can <resume/> the previous session */
     if (!conn->sm_disable && conn->sm_state->can_resume &&
         conn->sm_state->previd && conn->sm_state->bound_jid) {
         resume = xmpp_stanza_new(conn->ctx);

src/conn.c

@@ -1147,14 +1147,14 @@ long xmpp_conn_get_flags(const xmpp_conn_t *conn)
  *
  *  Supported flags are:
  *
- *    - XMPP_CONN_FLAG_DISABLE_TLS
- *    - XMPP_CONN_FLAG_MANDATORY_TLS
- *    - XMPP_CONN_FLAG_LEGACY_SSL
- *    - XMPP_CONN_FLAG_TRUST_TLS
- *    - XMPP_CONN_FLAG_LEGACY_AUTH
- *    - XMPP_CONN_FLAG_DISABLE_SM
- *    - XMPP_CONN_FLAG_ENABLE_COMPRESSION
- *    - XMPP_CONN_FLAG_COMPRESSION_DONT_RESET
+ *    - \ref XMPP_CONN_FLAG_DISABLE_TLS
+ *    - \ref XMPP_CONN_FLAG_MANDATORY_TLS
+ *    - \ref XMPP_CONN_FLAG_LEGACY_SSL
+ *    - \ref XMPP_CONN_FLAG_TRUST_TLS
+ *    - \ref XMPP_CONN_FLAG_LEGACY_AUTH
+ *    - \ref XMPP_CONN_FLAG_DISABLE_SM
+ *    - \ref XMPP_CONN_FLAG_ENABLE_COMPRESSION
+ *    - \ref XMPP_CONN_FLAG_COMPRESSION_DONT_RESET
  *
  *  @param conn a Strophe connection object
  *  @param flags ORed connection flags

strophe.h

@@ -707,11 +707,18 @@ void xmpp_rand_bytes(xmpp_rand_t *rand, unsigned char *output, size_t len);
  */
 void xmpp_rand_nonce(xmpp_rand_t *rand, char *output, size_t len);
 
-/**
+/*
  * Formerly "private but exported" functions made public for now to announce
  * deprecation */
 #include <stdarg.h>
 
+/**
+ * XMPP_DEPRECATED(x) macro to show a compiler warning for deprecated API
+ * functions
+ *
+ * @param x The function that can be used as a replacement or 'internal' if
+ * there is no replacement
+ */
 #if defined(__GNUC__)
 #if (__GNUC__ * 100 + __GNUC_MINOR__ >= 405)
 #define XMPP_DEPRECATED(x) __attribute__((deprecated("replaced by " #x)))