facebook-util: refactored naming and GTK-Doc

4 files changed, 71 insertions, 70 deletions

diff --git a/facebook/facebook-api.c b/facebook/facebook-api.c
index 57a22b0..e2460bc 100644
--- a/facebook/facebook-api.c
+++ b/facebook/facebook-api.c
@@ -683,7 +683,7 @@ fb_api_http_req(FbApi *api, const gchar *url, const gchar *name,
     fb_http_values_set_str(values, "format", "json");
     fb_http_values_set_str(values, "method", method);
 
-    data = fb_util_locale_str();
+    data = fb_util_get_locale();
     fb_http_values_set_str(values, "locale", data);
     g_free(data);
 
@@ -874,7 +874,7 @@ fb_api_cb_mqtt_open(FbMqtt *mqtt, gpointer data)
     fb_thrift_write_stop(thft);
 
     bytes = fb_thrift_get_bytes(thft);
-    cytes = fb_util_zcompress(bytes, &err);
+    cytes = fb_util_zlib_deflate(bytes, &err);
 
     FB_API_ERROR_EMIT(api, err,
         g_object_unref(thft);
@@ -1567,10 +1567,10 @@ fb_api_cb_mqtt_publish(FbMqtt *mqtt, const gchar *topic, GByteArray *pload,
         {"/t_p", fb_api_cb_publish_p}
     };
 
-    comp = fb_util_zcompressed(pload);
+    comp = fb_util_zlib_test(pload);
 
     if (G_LIKELY(comp)) {
-        bytes = fb_util_zuncompress(pload, &err);
+        bytes = fb_util_zlib_inflate(pload, &err);
         FB_API_ERROR_EMIT(api, err, return);
     } else {
         bytes = (GByteArray*) pload;
@@ -1630,11 +1630,11 @@ fb_api_rehash(FbApi *api)
     priv = api->priv;
 
     if (priv->cid == NULL) {
-        priv->cid = fb_util_randstr(32);
+        priv->cid = fb_util_rand_alnum(32);
     }
 
     if (priv->did == NULL) {
-        priv->did = fb_util_uuid();
+        priv->did = fb_util_rand_uuid();
     }
 
     if (priv->mid == 0) {
@@ -2070,7 +2070,7 @@ fb_api_publish(FbApi *api, const gchar *topic, const gchar *format, ...)
     va_end(ap);
 
     bytes = g_byte_array_new_take((guint8*) msg, strlen(msg));
-    cytes = fb_util_zcompress(bytes, &err);
+    cytes = fb_util_zlib_deflate(bytes, &err);
 
     FB_API_ERROR_EMIT(api, err,
         g_byte_array_free(bytes, TRUE);
diff --git a/facebook/facebook-id.h b/facebook/facebook-id.h
index 66161bb..f357caa 100644
--- a/facebook/facebook-id.h
+++ b/facebook/facebook-id.h
@@ -89,7 +89,7 @@
  *
  * Return: #TRUE if the string is an #FbId, otherwise #FALSE.
  */
-#define FB_ID_IS_STR(s) fb_util_str_is(s, G_ASCII_DIGIT)
+#define FB_ID_IS_STR(s) fb_util_strtest(s, G_ASCII_DIGIT)
 
 /**
  * FB_ID_TO_STR:
diff --git a/facebook/facebook-util.c b/facebook/facebook-util.c
index a436a46..0fadc6e 100644
--- a/facebook/facebook-util.c
+++ b/facebook/facebook-util.c
@@ -204,7 +204,7 @@ fb_util_debug_hexdump(FbDebugLevel level, const GByteArray *bytes,
 }
 
 gchar *
-fb_util_locale_str(void)
+fb_util_get_locale(void)
 {
     const gchar * const *langs;
     const gchar *lang;
@@ -232,7 +232,7 @@ fb_util_locale_str(void)
 }
 
 gchar *
-fb_util_randstr(gsize size)
+fb_util_rand_alnum(guint len)
 {
     gchar *ret;
     GRand *rand;
@@ -245,25 +245,34 @@ fb_util_randstr(gsize size)
         "0123456789";
     static const gsize charc = G_N_ELEMENTS(chars) - 1;
 
-    if (G_UNLIKELY(size < 1)) {
-        return NULL;
-    }
-
+    g_return_val_if_fail(len > 0, NULL);
     rand = g_rand_new();
-    ret = g_new(gchar, size + 1);
+    ret = g_new(gchar, len + 1);
 
-    for (i = 0; i < size; i++) {
+    for (i = 0; i < len; i++) {
         j = g_rand_int_range(rand, 0, charc);
         ret[i] = chars[j];
     }
 
-    ret[size] = 0;
+    ret[len] = 0;
     g_rand_free(rand);
     return ret;
 }
 
+gchar *
+fb_util_rand_uuid(void)
+{
+    guint8 buf[50];
+    sha1_state_t sha;
+
+    sha1_init(&sha);
+    random_bytes(buf, sizeof buf);
+    sha1_append(&sha, buf, sizeof buf);
+    return sha1_random_uuid(&sha);
+}
+
 gboolean
-fb_util_str_is(const gchar *str, GAsciiType type)
+fb_util_strtest(const gchar *str, GAsciiType type)
 {
     gsize i;
     gsize size;
@@ -283,20 +292,8 @@ fb_util_str_is(const gchar *str, GAsciiType type)
     return TRUE;
 }
 
-gchar *
-fb_util_uuid(void)
-{
-    guint8 buf[50];
-    sha1_state_t sha;
-
-    sha1_init(&sha);
-    random_bytes(buf, sizeof buf);
-    sha1_append(&sha, buf, sizeof buf);
-    return sha1_random_uuid(&sha);
-}
-
 gboolean
-fb_util_zcompressed(const GByteArray *bytes)
+fb_util_zlib_test(const GByteArray *bytes)
 {
     guint8 b0;
     guint8 b1;
@@ -315,7 +312,7 @@ fb_util_zcompressed(const GByteArray *bytes)
 }
 
 static GByteArray *
-fb_util_zconv(GConverter *conv, const GByteArray *bytes, GError **error)
+fb_util_zlib_conv(GConverter *conv, const GByteArray *bytes, GError **error)
 {
     GByteArray *ret;
     GConverterResult res;
@@ -358,25 +355,25 @@ fb_util_zconv(GConverter *conv, const GByteArray *bytes, GError **error)
 }
 
 GByteArray *
-fb_util_zcompress(const GByteArray *bytes, GError **error)
+fb_util_zlib_deflate(const GByteArray *bytes, GError **error)
 {
     GByteArray *ret;
     GZlibCompressor *conv;
 
     conv = g_zlib_compressor_new(G_ZLIB_COMPRESSOR_FORMAT_ZLIB, -1);
-    ret = fb_util_zconv(G_CONVERTER(conv), bytes, error);
+    ret = fb_util_zlib_conv(G_CONVERTER(conv), bytes, error);
     g_object_unref(conv);
     return ret;
 }
 
 GByteArray *
-fb_util_zuncompress(const GByteArray *bytes, GError **error)
+fb_util_zlib_inflate(const GByteArray *bytes, GError **error)
 {
     GByteArray *ret;
     GZlibDecompressor *conv;
 
     conv = g_zlib_decompressor_new(G_ZLIB_COMPRESSOR_FORMAT_ZLIB);
-    ret = fb_util_zconv(G_CONVERTER(conv), bytes, error);
+    ret = fb_util_zlib_conv(G_CONVERTER(conv), bytes, error);
     g_object_unref(conv);
     return ret;
 }
diff --git a/facebook/facebook-util.h b/facebook/facebook-util.h
index 5a0f1f4..1d5aee8 100644
--- a/facebook/facebook-util.h
+++ b/facebook/facebook-util.h
@@ -165,7 +165,7 @@ fb_util_debug_hexdump(FbDebugLevel level, const GByteArray *bytes,
                       G_GNUC_PRINTF(3, 4);
 
 /**
- * fb_util_locale_str:
+ * fb_util_get_locale:
  *
  * Gets the locale string (ex: en_US) from the system. The returned
  * string should be freed with #g_free() when no longer needed.
@@ -173,78 +173,82 @@ fb_util_debug_hexdump(FbDebugLevel level, const GByteArray *bytes,
  * Returns: The locale string.
  */
 gchar *
-fb_util_locale_str(void);
+fb_util_get_locale(void);
 
 /**
- * fb_util_randstr:
- * @size: The size of the string.
+ * fb_util_rand_alnum:
+ * @len: The length of the string.
  *
- * Gets a random alphanumeric string. The returned string should be
- * freed with #g_free() when no longer needed.
+ * Gets a random alphanumeric (A-Za-z0-9) string. This function should
+ * *not* be relied on for cryptographic operations. The returned string
+ * should be freed with #g_free() when no longer needed.
  *
- * Returns: The random string.
+ * Returns: The alphanumeric string.
  */
 gchar *
-fb_util_randstr(gsize size);
+fb_util_rand_alnum(guint len);
 
 /**
- * fb_util_str_is:
- * @str: The string.
- * @type: The #GAsciiType.
+ * fb_util_rand_uuid:
  *
- * Determines if @str abides to the #GAsciiType.
+ * Gets a random UUID string. The returned string should be freed with
+ * #g_free() when no longer needed.
  *
- * Returns: #TRUE if the string abides to @type, otherwise #FALSE.
+ * Returns: The UUID string.
  */
-gboolean
-fb_util_str_is(const gchar *str, GAsciiType type);
+gchar *
+fb_util_rand_uuid(void);
 
 /**
- * fb_util_uuid:
+ * fb_util_strtest:
+ * @str: The string.
+ * @type: The #GAsciiType.
  *
- * Gets a random UUID string. The returned string should be freed with
- * #g_free() when no longer needed.
+ * Tests if the string only contains characters allowed by the
+ * #GAsciiType. More than one type can be specified by ORing the types
+ * together.
  *
- * Returns: The UUID string.
+ * Returns: #TRUE if the string only contains characters allowed by the
+ *          #GAsciiType, otherwise #FALSE.
  */
-gchar *
-fb_util_uuid(void);
+gboolean
+fb_util_strtest(const gchar *str, GAsciiType type);
 
 /**
- * fb_util_zcompressed:
+ * fb_util_zlib_test:
  * @bytes: The #GByteArray.
  *
- * Determines if the #GByteArray is zlib compressed.
+ * Tests if the #GByteArray is zlib compressed.
  *
  * Returns: #TRUE if the #GByteArray is compressed, otherwise #FALSE.
  */
 gboolean
-fb_util_zcompressed(const GByteArray *bytes);
+fb_util_zlib_test(const GByteArray *bytes);
 
 /**
- * fb_util_zcompress:
+ * fb_util_zlib_deflate:
  * @bytes: The #GByteArray.
  * @error: The return location for the #GError or #NULL.
  *
- * Compresses a #GByteArray with zlib. The returned #GByteArray should
- * be freed with #g_byte_array_free() when no longer needed.
+ * Deflates a #GByteArray with zlib. The returned #GByteArray should be
+ * freed with #g_byte_array_free() when no longer needed.
  *
- * Returns: The compressed #GByteArray.
+ * Returns: The deflated #GByteArray or #NULL on error.
  */
 GByteArray *
-fb_util_zcompress(const GByteArray *bytes, GError **error);
+fb_util_zlib_deflate(const GByteArray *bytes, GError **error);
 
 /**
- * fb_util_zuncompress:
+ * fb_util_zlib_inflate:
  * @bytes: The #GByteArray.
  * @error: The return location for the #GError or #NULL.
  *
- * Uncompresses a #GByteArray with zlib. The returned #GByteArray
- * should be freed with #g_byte_array_free() when no longer needed.
+ * Inflates a #GByteArray with zlib. The returned #GByteArray should be
+ * freed with #g_byte_array_free() when no longer needed.
  *
- * Returns: The uncompressed #GByteArray or #NULL on error.
+ * Returns: The inflated #GByteArray or #NULL on error.
  */
 GByteArray *
-fb_util_zuncompress(const GByteArray *bytes, GError **error);
+fb_util_zlib_inflate(const GByteArray *bytes, GError **error);
 
 #endif /* _FACEBOOK_UTIL_H_ */