/soc/2015/jgeboski/facebook: 34d43f8c10d1: facebook: added GTK-D...

James Geboski <[email protected]> Sat, 15 Aug 2015 16:25:46 -0400
Newsgroups	gmane.comp.gnome.gaim.cvs
Message-ID	<[email protected]>
Changeset: 34d43f8c10d13a569f42ff3196b9b72a9bbf67c9
Author:	 James Geboski <[email protected]>
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 @@
+@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),

_______________________________________________
Commits mailing list
[email protected]
https://pidgin.im/cgi-bin/mailman/listinfo/commits