docs: add documentation for in-tree plugins

This achieves 100% symbol coverage, hurray!

diff --git a/docs/Makefile.am b/docs/Makefile.am
index f9bf52e..91445a1 100644 (file)
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -22,7 +22,9 @@ DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
 # gtk-doc will search all .c and .h files beneath these paths
 # for inline comments documenting functions and macros.
 # e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk
-DOC_SOURCE_DIR=$(top_srcdir)/include $(top_srcdir)/src/common
+DOC_SOURCE_DIR=$(top_srcdir)/include\
+$(top_srcdir)/src/common\
+$(top_srcdir)/src/plugins
 
 # Extra options to pass to gtkdoc-scangobj. Not normally needed.
 SCANGOBJ_OPTIONS=
@@ -92,7 +94,10 @@ expand_content_files=
 GTKDOC_CFLAGS=
     
 GTKDOC_LIBS=\
-    $(top_builddir)/src/common/libgsignond-common.la
+    $(top_builddir)/src/common/libgsignond-common.la\
+    $(top_builddir)/src/plugins/digest/libdigest.la\
+    $(top_builddir)/src/plugins/password/libpassword.la\
+    $(top_builddir)/src/plugins/ssotest/libssotest.la
 
 # This includes the standard gtk-doc make rules, copied by gtkdocize.
 include $(top_srcdir)/gtk-doc.make

diff --git a/docs/gsignond-docs.sgml b/docs/gsignond-docs.sgml
index 631193a..e2cde9a 100644 (file)
--- a/docs/gsignond-docs.sgml
+++ b/docs/gsignond-docs.sgml
@@ -35,6 +35,13 @@
     <xi:include href="xml/gsignond-utils.xml"/>
 
   </chapter>
+  <chapter>
+    <title>Standard in-tree authorization plugins</title>
+    <xi:include href="xml/gsignond-digest-plugin.xml"/>
+    <xi:include href="xml/gsignond-ssotest-plugin.xml"/>
+    <xi:include href="xml/gsignond-password-plugin.xml"/>
+
+  </chapter>
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
      <xi:include href="xml/tree_index.sgml"/>

diff --git a/src/plugins/digest/gsignond-digest-plugin.c b/src/plugins/digest/gsignond-digest-plugin.c
index bbbb8f4..b0e9c19 100644 (file)
--- a/src/plugins/digest/gsignond-digest-plugin.c
+++ b/src/plugins/digest/gsignond-digest-plugin.c
@@ -31,6 +31,46 @@
 #include <gsignond/gsignond-error.h>
 #include <gsignond/gsignond-log.h>
 
+/**
+ * SECTION:gsignond-digest-plugin
+ * @short_description: a plugin that performs HTTP Digest authorization
+ * @include: gsignond/gsignond-digest-plugin.h
+ *
+ * #GSignondDigestPlugin performs HTTP Digest authorization without exposing
+ * the password to the application. Digest authorization is described in 
+ * <ulink url="http://tools.ietf.org/html/rfc2617">RFC 2617</ulink>.
+ * 
+ * gsignond_plugin_request_initial() @session_data parameter should include
+ * the following string items, whose meaning is described in the RFC: 
+ * - username and secret. If they are absent, they are requested from the user
+ * via gSSO UI.
+ * - realm, "Algo", "Nonce",  "Method", "DigestUri" - mandatory items.
+ * - "NonceCount", "Qop",  "HEntity". "NonceCount" must be present if "Qop" is 
+ * present, "HEntity" must be present if "Qop" is present and set to "auth-int".
+ * 
+ * If the plugin has all the data to calculate the digest, it issues 
+ * #GSignondPlugin::response-final signal. @session_data in that signal contains
+ * the username, "CNonce" item and the digest value under the "Response" key.
+ * 
+ * If some of the data is incorrect or not available, #GSignondPlugin::error
+ * signal is issued instead.
+ * 
+ * #GSignondPlugin:type property is set to "digest", and #GSignondPlugin:mechanisms 
+ * property contains a single entry "digest".
+ */
+/**
+ * GSignondDigestPlugin:
+ *
+ * Opaque #GSignondDigestPlugin data structure.
+ */
+/**
+ * GSignondDigestPluginClass:
+ * @parent_class: the parent class structure
+ *
+ * Opaque #GSignondDigestPluginClass data structure.
+ */
+
+
 static void gsignond_plugin_interface_init (GSignondPluginInterface *iface);
 
 G_DEFINE_TYPE_WITH_CODE (GSignondDigestPlugin, gsignond_digest_plugin,

diff --git a/src/plugins/password/gsignond-password-plugin.c b/src/plugins/password/gsignond-password-plugin.c
index e354fff..cc3e254 100644 (file)
--- a/src/plugins/password/gsignond-password-plugin.c
+++ b/src/plugins/password/gsignond-password-plugin.c
@@ -27,6 +27,36 @@
 #include "gsignond-password-plugin.h"
 #include <gsignond/gsignond-error.h>
 
+/**
+ * SECTION:gsignond-password-plugin
+ * @short_description: a plugin for retrieving the username/password
+ * @include: gsignond/gsignond-password-plugin.h
+ *
+ * #GSignondPasswordPlugin is used in login/password based authorization protocols.
+ * It returns to the applications the username and password associated with an
+ * identity. The plugin first checks if the daemon has placed them in
+ * gsignond_plugin_request_initial() @session_data parameter
+ * (that means they're already stored in gSSO secure database), and if not,
+ * the user is asked for the username and password via gSSO UI.
+ *
+ * The plugin returns the username and password via #GSignondPlugin::response-final
+ * if it was able to obtain them, and issues #GSignondPlugin::error otherwise.
+ * 
+ * #GSignondPlugin:type property is set to "password", and #GSignondPlugin:mechanisms 
+ * property contains a single entry "password".
+ */
+/**
+ * GSignondPasswordPlugin:
+ *
+ * Opaque #GSignondPasswordPlugin data structure.
+ */
+/**
+ * GSignondPasswordPluginClass:
+ * @parent_class: the parent class structure
+ *
+ * Opaque #GSignondPasswordPluginClass data structure.
+ */
+
 static void gsignond_plugin_interface_init (GSignondPluginInterface *iface);
 
 G_DEFINE_TYPE_WITH_CODE (GSignondPasswordPlugin, gsignond_password_plugin, 

diff --git a/src/plugins/ssotest/gsignond-ssotest-plugin.c b/src/plugins/ssotest/gsignond-ssotest-plugin.c
index 313a7db..f414577 100644 (file)
--- a/src/plugins/ssotest/gsignond-ssotest-plugin.c
+++ b/src/plugins/ssotest/gsignond-ssotest-plugin.c
@@ -29,6 +29,26 @@
 
 #include "gsignond-ssotest-plugin.h"
 
+/**
+ * SECTION:gsignond-ssotest-plugin
+ * @short_description: a plugin that is used internally in gsignond unit test
+ * @include: gsignond/gsignond-ssotest-plugin.h
+ *
+ * #GSignondSsoTestPlugin is used by gsignond unit tests. It should not be used
+ * by applications.
+ */
+/**
+ * GSignondSsoTestPlugin:
+ *
+ * Opaque #GSignondSsoTestPlugin data structure.
+ */
+/**
+ * GSignondSsoTestPluginClass:
+ * @parent_class: the parent class structure
+ *
+ * Opaque #GSignondSsoTestPluginClass data structure.
+ */
+
 #define GSIGNOND_SSOTEST_PLUGIN_GET_PRIVATE(obj) \
     (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
                                   GSIGNOND_TYPE_SSOTEST_PLUGIN, \