/soc/2015/jgeboski/facebook: 34d43f8c10d1: facebook: added GTK-D...
James Geboski
jgeboski at gmail.com
Sat Aug 15 16:25:46 EDT 2015
Changeset: 34d43f8c10d13a569f42ff3196b9b72a9bbf67c9
Author: James Geboski <jgeboski at gmail.com>
Date: 2015-08-15 16:25 -0400
Branch: facebook
URL: https://hg.pidgin.im/soc/2015/jgeboski/facebook/rev/34d43f8c10d1
Description:
facebook: added GTK-Doc for the internal APIs
diffstat:
configure.ac | 3 +
doc/reference/Makefile.am | 2 +-
doc/reference/protocols/Makefile.am | 2 +
doc/reference/protocols/facebook/Makefile.am | 126 ++++
doc/reference/protocols/facebook/facebook-docs.xml | 32 +
doc/reference/protocols/version.xml.in | 1 +
libpurple/protocols/facebook/api.c | 168 +++++-
libpurple/protocols/facebook/api.h | 605 +++++++++++++++++++-
libpurple/protocols/facebook/data.h | 182 ++++++-
libpurple/protocols/facebook/facebook.h | 28 +-
libpurple/protocols/facebook/http.h | 186 ++++++-
libpurple/protocols/facebook/id.h | 106 +++-
libpurple/protocols/facebook/json.h | 366 ++++++++++++-
libpurple/protocols/facebook/mqtt.c | 82 ++-
libpurple/protocols/facebook/mqtt.h | 452 ++++++++++++++-
libpurple/protocols/facebook/thrift.h | 412 ++++++++++++++-
libpurple/protocols/facebook/util.h | 231 +++++++-
17 files changed, 2833 insertions(+), 151 deletions(-)
diffs (truncated from 4283 to 300 lines):
diff --git a/configure.ac b/configure.ac
--- a/configure.ac
+++ b/configure.ac
@@ -2730,6 +2730,9 @@ AC_CONFIG_FILES([Makefile
doc/reference/finch/version.xml
doc/reference/libpurple/Makefile
doc/reference/libpurple/version.xml
+ doc/reference/protocols/Makefile
+ doc/reference/protocols/facebook/Makefile
+ doc/reference/protocols/version.xml
doc/reference/pidgin/Makefile
doc/reference/pidgin/version.xml
m4macros/Makefile
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -6,4 +6,4 @@ if ENABLE_GNT
GNT_DIR=finch
endif
-SUBDIRS = libpurple $(GNT_DIR) $(GTK_DIR)
+SUBDIRS = libpurple protocols $(GNT_DIR) $(GTK_DIR)
diff --git a/doc/reference/protocols/Makefile.am b/doc/reference/protocols/Makefile.am
new file mode 100644
--- /dev/null
+++ b/doc/reference/protocols/Makefile.am
@@ -0,0 +1,2 @@
+EXTRA_DIST = version.xml.in
+SUBDIRS = facebook
diff --git a/doc/reference/protocols/facebook/Makefile.am b/doc/reference/protocols/facebook/Makefile.am
new file mode 100644
--- /dev/null
+++ b/doc/reference/protocols/facebook/Makefile.am
@@ -0,0 +1,126 @@
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=facebook
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+#DOC_MODULE_VERSION=2
+
+# The top-level XML file (SGML in the past). You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR=$(top_srcdir)/libpurple/protocols/$(DOC_MODULE)
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS=\
+ --deprecated-guards="PURPLE_DISABLE_DEPRECATED" \
+ --rebuild-types \
+ --rebuild-sections
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml
+MKDB_OPTIONS=--xml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS=
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=$(top_srcdir)/libpurple/protocols/$(DOC_MODULE)/*.h
+CFILE_GLOB=$(top_srcdir)/libpurple/protocols/$(DOC_MODULE)/*.c
+
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+# TODO: those files are not properly scanned when building out-of-tree
+EXTRA_HFILES =
+
+# Header files or dirs to ignore when scanning. Use base file/dir names
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
+IGNORE_HFILES=marshal.h
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files = ../version.xml
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_CFLAGS = \
+ -I$(top_srcdir) \
+ -I$(top_srcdir)/libpurple/protocols/$(DOC_MODULE) \
+ $(GLIB_CFLAGS) \
+ $(GPLUGIN_CFLAGS) \
+ $(DEBUG_CFLAGS) \
+ $(JSON_CFLAGS) \
+ $(ZLIB_CFLAGS) \
+ $(INTROSPECTION_CFLAGS)
+
+GTKDOC_LIBS = \
+ $(top_builddir)/libpurple/protocols/$(DOC_MODULE)/lib$(DOC_MODULE).la \
+ $(STATIC_LINK_LIBS) \
+ $(GLIB_LIBS) \
+ $(GPLUGIN_LIBS) \
+ $(INTLLIBS) \
+ $(JSON_LIBS) \
+ $(ZLIB_LIBS) \
+ $(INTROSPECTION_LIBS)
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST += version.xml.in
+
+# Files not to distribute
+# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
+# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
+DISTCLEANFILES = $(DOC_MODULE).types $(DOC_MODULE)-sections.txt
+
+dist-hook: html-build.stamp
+
+# Comment this out if you want 'make check' to test you doc status
+# and run some sanity checks
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = \
+ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
+ SRCDIR=$(abs_srcdir)
+#TODO: fix and enable
+#TESTS = $(GTKDOC_CHECK)
+endif
diff --git a/doc/reference/protocols/facebook/facebook-docs.xml b/doc/reference/protocols/facebook/facebook-docs.xml
new file mode 100644
--- /dev/null
+++ b/doc/reference/protocols/facebook/facebook-docs.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+
+<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+ <bookinfo>
+ <title>Purple Reference Manual</title>
+ <abstract>
+ <title>Facebook Plugin &version;</title>
+ <para>
+ The Facebook Messenger protocol plugin for libpurple.
+ </para>
+ </abstract>
+ </bookinfo>
+
+ <reference label="II">
+ <title>API Reference</title>
+
+ <xi:include href="xml/api.xml" />
+ <xi:include href="xml/data.xml" />
+ <xi:include href="xml/facebook.xml" />
+ <xi:include href="xml/http.xml" />
+ <xi:include href="xml/id.xml" />
+ <xi:include href="xml/json.xml" />
+ <xi:include href="xml/mqtt.xml" />
+ <xi:include href="xml/thrift.xml" />
+ <xi:include href="xml/util.xml" />
+ </reference>
+</book>
diff --git a/doc/reference/protocols/version.xml.in b/doc/reference/protocols/version.xml.in
new file mode 100644
--- /dev/null
+++ b/doc/reference/protocols/version.xml.in
@@ -0,0 +1,1 @@
+ at PURPLE_VERSION@
diff --git a/libpurple/protocols/facebook/api.c b/libpurple/protocols/facebook/api.c
--- a/libpurple/protocols/facebook/api.c
+++ b/libpurple/protocols/facebook/api.c
@@ -167,36 +167,76 @@ fb_api_class_init(FbApiClass *klass)
gklass->dispose = fb_api_dispose;
g_type_class_add_private(klass, sizeof (FbApiPrivate));
+ /**
+ * FbApi:cid:
+ *
+ * The client identifier for MQTT. This value should be saved
+ * and loaded for persistence.
+ */
props[PROP_CID] = g_param_spec_string(
"cid",
"Client ID",
"Client identifier for MQTT",
NULL,
G_PARAM_READWRITE);
+
+ /**
+ * FbApi:did:
+ *
+ * The device identifier for the MQTT message queue. This value
+ * should be saved and loaded for persistence.
+ */
props[PROP_DID] = g_param_spec_string(
"did",
"Device ID",
- "Device identifier",
+ "Device identifier for the MQTT message queue",
NULL,
G_PARAM_READWRITE);
+
+ /**
+ * FbApi:mid:
+ *
+ * The MQTT identifier. This value should be saved and loaded
+ * for persistence.
+ */
props[PROP_MID] = g_param_spec_uint64(
"mid",
"MQTT ID",
- "MQTT identifier for the MQTT queuer",
+ "MQTT identifier",
0, G_MAXUINT64, 0,
G_PARAM_READWRITE);
+
+ /**
+ * FbApi:stoken:
+ *
+ * The synchronization token for the MQTT message queue. This
+ * value should be saved and loaded for persistence.
+ */
props[PROP_STOKEN] = g_param_spec_string(
"stoken",
"Sync Token",
- "Synchronization token for the MQTT queue",
+ "Synchronization token for the MQTT message queue",
NULL,
G_PARAM_READWRITE);
+
+ /**
+ * FbApi:token:
+ *
+ * The access token for authentication. This value should be
+ * saved and loaded for persistence.
+ */
props[PROP_TOKEN] = g_param_spec_string(
"token",
"Access Token",
- "Access token from authenticating",
+ "Access token for authentication",
NULL,
G_PARAM_READWRITE);
+
+ /**
+ * FbApi:uid:
+ *
+ * The #FbId of the user of the #FbApi.
+ */
props[PROP_UID] = g_param_spec_int64(
"uid",
"User ID",
@@ -205,6 +245,13 @@ fb_api_class_init(FbApiClass *klass)
G_PARAM_READWRITE);
g_object_class_install_properties(gklass, PROP_N, props);
+ /**
+ * FbApi::auth:
+ * @api: The #FbApi.
+ *
+ * Emitted upon the successful completion of the authentication
+ * process. This is emitted as a result of #fb_api_auth().
+ */
g_signal_new("auth",
G_TYPE_FROM_CLASS(klass),
More information about the Commits
mailing list