Add documentation support and stub documentation to Folks

Add valadoc documentation support in the build system, and add stub
documentation to the top level of all the classes in the Folks namespace, but
not the Folks.Backends namespace.

The documentation is generated in HTML format in docs/folks-0.1/ but isn't
distributed in the tarball.

diff --git a/Makefile.am b/Makefile.am
index 1735ad1..8a457d2 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -3,6 +3,10 @@ SUBDIRS = \
        backends \
        $(NULL)
 
+if ENABLE_DOCS
+SUBDIRS += docs
+endif
+
 ACLOCAL_AMFLAGS = -I m4
 
 DISTCHECK_CONFIGURE_FLAGS =            \

diff --git a/configure.ac b/configure.ac
index 1d3a442..6fc7eab 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -64,6 +64,20 @@ AC_SUBST(LIBFOLKS_CFLAGS)
 AC_SUBST(LIBFOLKS_LIBS)
 
 # -----------------------------------------------------------
+# Documentation
+# -----------------------------------------------------------
+AC_ARG_ENABLE(docs,
+  AC_HELP_STRING([--enable-docs],[Enable documentation generation]),
+    enable_docs=$enableval, enable_docs=no)
+AM_CONDITIONAL(ENABLE_DOCS, test x$enable_docs = xyes)
+
+AS_IF([test "x$enable_docs" != xno],
+  [AC_PATH_PROG(VALADOC, valadoc, :)
+   AC_SUBST(VALADOC)
+   AS_IF([test "$VALADOC" = :],
+     [AC_MSG_ERROR([valadoc not found])])])
+
+# -----------------------------------------------------------
 # Telepathy backend
 # -----------------------------------------------------------
 PKG_CHECK_MODULES(LIBFOLKS_TELEPATHY,
@@ -150,6 +164,7 @@ AC_CONFIG_FILES([
        backends/Makefile
        backends/telepathy/Makefile
        folks/Makefile
+       docs/Makefile
 ])
 
 AC_OUTPUT
@@ -163,6 +178,7 @@ Configure summary:
         Coding style checks.........:  ${ENABLE_CODING_STYLE_CHECKS}
         VAPI generation.............:  ${enable_vapigen}
         Bugreporting URL............:  ${PACKAGE_BUGREPORT}
+        Documentation...............:  ${enable_docs}
 
 
 "

diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644 (file)
index 0000000..3345521
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1 @@
+folks-0.1

diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644 (file)
index 0000000..4c29331
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1,30 @@
+docdir=$(datadir)/devhelp/references/folks-0.1
+innerdocdir=$(datadir)/devhelp/references/folks-0.1/folks-0.1
+imgdir=$(datadir)/devhelp/references/folks-0.1/folks-0.1/img
+
+doc_data = \
+       folks-0.1/*.css \
+       folks-0.1/*.png \
+       $(NULL)
+
+doc_DATA = \
+       folks-0.1/index.html \
+       $(doc_data) \
+       $(NULL)
+
+innerdoc_DATA = \
+       folks-0.1/folks-0.1/index.htm \
+       folks-0.1/folks-0.1/*.html \
+       $(NULL)
+
+img_DATA = \
+       folks-0.1/folks-0.1/img/*.png \
+       $(NULL)
+
+$(doc_data) $(innerdoc_DATA) $(img_DATA): folks-0.1/index.html
+
+folks-0.1/index.html:
+       $(VALADOC) -o folks-0.1/ --force -b $(top_srcdir) \
+               --pkg=gee-1.0 --pkg=gio-2.0 --pkg=gmodule-2.0 --pkg=build-conf \
+               --vapidir=$(top_srcdir)/folks \
+               $(top_srcdir)/folks/*.vala

diff --git a/folks/alias.vala b/folks/alias.vala
index 70c4664..e3a4f04 100644 (file)
--- a/folks/alias.vala
+++ b/folks/alias.vala
@@ -20,6 +20,10 @@
 
 using GLib;
 
+/**
+ * Interface for classes which represent aliasable contacts, such as
+ * {@link Persona} and {@link Individual}.
+ */
 public interface Folks.Alias : Object
 {
   public abstract string alias { get; set; }

diff --git a/folks/avatar.vala b/folks/avatar.vala
index 0e3522b..81bc50d 100644 (file)
--- a/folks/avatar.vala
+++ b/folks/avatar.vala
@@ -20,6 +20,10 @@
 
 using GLib;
 
+/**
+ * Interface for classes which represent contacts which have an avatar
+ * (pictorial representation), such as {@link Persona} and {@link Individual}.
+ */
 public interface Folks.Avatar : Object
 {
   public abstract File avatar { get; set; }

diff --git a/folks/backend.vala b/folks/backend.vala
index fd3785a..77de397 100644 (file)
--- a/folks/backend.vala
+++ b/folks/backend.vala
@@ -21,6 +21,11 @@
 using BuildConf;
 using Folks;
 
+/**
+ * A single backend to libfolks, such as Telepathy or evolution-data-server.
+ * Each backend provides {@link Persona}s which are aggregated to form
+ * {@link Individual}s.
+ */
 public abstract class Folks.Backend : Object
 {
   public abstract string name { get; protected set; }

diff --git a/folks/capabilities.vala b/folks/capabilities.vala
index 99c4d29..714acfc 100644 (file)
--- a/folks/capabilities.vala
+++ b/folks/capabilities.vala
@@ -20,15 +20,47 @@
 
 using GLib;
 
+/**
+ * Flag values for the capabilities an object implementing {@link Capabilities}
+ * could possibly have, as a bitmask.
+ */
 public enum Folks.CapabilitiesFlags {
+  /**
+   * No capabilities. Mutually exclusive with the other values.
+   */
   NONE = 0,
+
+  /**
+   * Audio chat support.
+   */
   AUDIO = 1 << 0,
+
+  /**
+   * Video chat support.
+   */
   VIDEO = 1 << 1,
+
+  /**
+   * File transfer support.
+   */
   FILE_TRANSFER = 1 << 2,
+
+  /**
+   * Telepathy tubes support.
+   */
   STREAM_TUBE = 1 << 3,
+
+  /**
+   * Unknown set of capabilities. Mutually exclusive with the other values.
+   */
   UNKNOWN = 1 << 7,
 }
 
+/**
+ * Interface exposing the capabilities of the {@link Persona} or
+ * {@link Individual} implementing it, such as whether they can do video chats
+ * or file transfers.
+ */
 public interface Folks.Capabilities : Object
 {
   public abstract CapabilitiesFlags capabilities

diff --git a/folks/groups.vala b/folks/groups.vala
index f674cda..dbb893d 100644 (file)
--- a/folks/groups.vala
+++ b/folks/groups.vala
@@ -20,6 +20,10 @@
 
 using GLib;
 
+/**
+ * Interface for {@link Persona}s or {@link Individual}s which can be grouped
+ * into sets of similar objects.
+ */
 public interface Folks.Groups : Object
 {
   public abstract HashTable<string, bool> groups { get; set; }

diff --git a/folks/individual-aggregator.vala b/folks/individual-aggregator.vala
index dbcb4e9..79da5dc 100644 (file)
--- a/folks/individual-aggregator.vala
+++ b/folks/individual-aggregator.vala
@@ -22,6 +22,11 @@ using Folks;
 using Gee;
 using GLib;
 
+/**
+ * Allows access to the {@link Individual}s which have been created through
+ * aggregation of all the {@link Persona}s provided by the various libfolks
+ * {@link Backend}s. This is the main interface for accessing libfolks.
+ */
 public class Folks.IndividualAggregator : Object
 {
   private BackendStore backend_store;

diff --git a/folks/individual.vala b/folks/individual.vala
index d48c466..6e863e5 100644 (file)
--- a/folks/individual.vala
+++ b/folks/individual.vala
@@ -22,6 +22,10 @@ using Gee;
 using GLib;
 using Folks;
 
+/**
+ * A physical person, aggregated from the various {@link Persona}s the person
+ * might have, such as their different IM addresses or vCard entries.
+ */
 public class Folks.Individual : Object, Alias, Avatar, Capabilities, Groups,
        Presence
 {

diff --git a/folks/persona-store.vala b/folks/persona-store.vala
index f7a2e44..8a37efa 100644 (file)
--- a/folks/persona-store.vala
+++ b/folks/persona-store.vala
@@ -21,6 +21,9 @@
 using GLib;
 using Folks;
 
+/**
+ * A store for {@link Persona}s.
+ */
 public abstract class Folks.PersonaStore : Object
 {
   public abstract signal void personas_added (GLib.List<Persona> personas);

diff --git a/folks/persona.vala b/folks/persona.vala
index 9d221cf..1ae4af5 100644 (file)
--- a/folks/persona.vala
+++ b/folks/persona.vala
@@ -21,6 +21,12 @@
 using GLib;
 using Folks;
 
+/**
+ * Represents a "shard" of a person from a single source (a single
+ * {@link Backend}), such as an XMPP contact from Telepathy or a vCard contact
+ * from evolution-data-server. All the personas belonging to one physical person
+ * are aggregated to form a single {@link Individual} representing that person.
+ */
 public abstract class Folks.Persona : Object, Alias, Avatar, Capabilities,
        Presence
 {

diff --git a/folks/presence.vala b/folks/presence.vala
index af4d656..5f3f75c 100644 (file)
--- a/folks/presence.vala
+++ b/folks/presence.vala
@@ -20,18 +20,65 @@
 
 using GLib;
 
+/**
+ * The possible presence states an object implementing {@link Presence} could be
+ * in.
+ *
+ * These closely follow the
+ * [[http://telepathy.freedesktop.org/spec/Connection_Interface_Simple_Presence.html#Connection_Presence_Type|SimplePresence]]
+ * interface in the Telepathy specification.
+ */
 public enum Folks.PresenceType {
+  /**
+   * Presence is unset. (Default.)
+   */
   UNSET,
+
+  /**
+   * User is offline.
+   */
   OFFLINE,
+
+  /**
+   * User is available.
+   */
   AVAILABLE,
+
+  /**
+   * User is away.
+   */
   AWAY,
+
+  /**
+   * User is away for an extended period.
+   */
   EXTENDED_AWAY,
+
+  /**
+   * User is online but hidden.
+   */
   HIDDEN,
+
+  /**
+   * User is busy.
+   */
   BUSY,
+
+  /**
+   * Presence is unknown.
+   */
   UNKNOWN,
+
+  /**
+   * Presence is invalid.
+   */
   ERROR
 }
 
+/**
+ * Interface for {@link Persona}s or {@link Individual}s which have a presence;
+ * their current availability, such as for chatting.
+ */
 public interface Folks.Presence : Object
 {
   public abstract Folks.PresenceType presence_type