From a6d8f4bb835dc01344861e26b78867273322cb52 Mon Sep 17 00:00:00 2001
From: Marcel Holtmann <marcel@holtmann.org>
Date: Thu, 14 Aug 2008 01:25:48 +0200
Subject: [PATCH] First steps into providing API documentation

---
 doc/Makefile.am      | 19 +++++++++++++------
 doc/connman-docs.xml |  2 ++
 include/log.h        | 14 ++++++++++++++
 include/plugin.h     | 18 +++++++++++++++++-
 src/log.c            | 24 ++++++++++++++++++++++++
 src/plugin.c         |  2 --
 6 files changed, 70 insertions(+), 9 deletions(-)

diff --git a/doc/Makefile.am b/doc/Makefile.am
index c7b59b6..a2e9205 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -5,25 +5,32 @@ DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml
 
 DOC_SOURCE_DIR = ../src
 
-MKDB_OPTIONS = --sgml-mode --output-format=xml --tmpl-dir=.
+SCAN_OPTIONS = --rebuild-sections --source-dir=../include
+
+MKDB_OPTIONS = --sgml-mode --output-format=xml --tmpl-dir=. \
+						--ignore-files=connman \
+						--source-dir=../include \
+						--source-suffixes=c,h
 
 MKTMPL_OPTIONS = --output-dir=.
 
 HFILE_GLOB = $(top_srcdir)/include/*.h
-CFILE_GLOB = $(top_srcdir)/src/*.c
+CFILE_GLOB = $(top_srcdir)/src/*.c $(top_srcdir)/src/*.h
 
-IGNORE_HFILES = config.h connman.h
+IGNORE_HFILES = connman connman.h supplicant.h \
+		iface.h rtnl.h dbus.h element.h property.h driver.h security.h
 
 HTML_IMAGES =
 
 content_files = connman-introduction.xml
 
-INCLUDES = -I$(top_srcdir) $(GLIB_CFLAGS) $(DBUS_CFLAGS)
+INCLUDES = -I$(top_srcdir)/include -I$(top_srcdir)/gdbus \
+	$(GTHREAD_CFLAGS) $(GMODULE_CFLAGS) $(GLIB_CFLAGS) $(DBUS_CFLAGS)
 
-GTKDOC_LIBS =
+GTKDOC_LIBS = $(DBUS_LIBS) $(GLIB_LIBS) $(GMODULE_LIBS) $(GTHREAD_LIBS)
 
 MAINTAINERCLEANFILES = Makefile.in \
-	$(DOC_MODULE).types $(DOC_MODULE)-*.sgml $(DOC_MODULE)-*.txt
+	$(DOC_MODULE).types $(DOC_MODULE)-*.txt *.sgml
 
 if ENABLE_GTK_DOC
 include $(top_srcdir)/doc/gtk-doc.make
diff --git a/doc/connman-docs.xml b/doc/connman-docs.xml
index d070a3d..4674a62 100644
--- a/doc/connman-docs.xml
+++ b/doc/connman-docs.xml
@@ -64,6 +64,8 @@
 	This part presents the function reference for Connection Manager.
       </para>
     </partintro>
+    <xi:include href="xml/log.xml" />
+    <xi:include href="xml/plugin.xml" />
   </reference>
 
   <appendix id="license">
diff --git a/include/log.h b/include/log.h
index 8a0b5a5..81a5bc4 100644
--- a/include/log.h
+++ b/include/log.h
@@ -26,10 +26,24 @@
 extern "C" {
 #endif
 
+/**
+ * SECTION:log
+ * @title: Logging premitives
+ * @short_description: Functions for logging error and debug information
+ */
+
 extern void connman_info(const char *format, ...);
 extern void connman_error(const char *format, ...);
 extern void connman_debug(const char *format, ...);
 
+/**
+ * DBG:
+ * @fmt: format string
+ * @arg...: list of arguments
+ *
+ * Simple macro around connman_debug() which also include the function
+ * name it is called in.
+ */
 #define DBG(fmt, arg...) connman_debug("%s:%s() " fmt, __FILE__, __FUNCTION__ , ## arg)
 
 #ifdef __cplusplus
diff --git a/include/plugin.h b/include/plugin.h
index 387a48c..427ceed 100644
--- a/include/plugin.h
+++ b/include/plugin.h
@@ -26,6 +26,12 @@
 extern "C" {
 #endif
 
+/**
+ * SECTION:plugin
+ * @title: Plugin premitives
+ * @short_description: Functions for declaring plugins
+ */
+
 struct connman_plugin_desc {
 	const char *name;
 	const char *description;
@@ -34,7 +40,17 @@ struct connman_plugin_desc {
 	void (*exit) (void);
 };
 
-#define CONNMAN_PLUGIN_DEFINE(name,description,version,init,exit) \
+/**
+ * CONNMAN_PLUGIN_DEFINE:
+ * @name: plugin name
+ * @description: plugin description
+ * @version: plugin version string
+ * @init: init function called on plugin loading
+ * @exit: exit function called on plugin removal
+ *
+ * Macro for defining a plugin descriptor
+ */
+#define CONNMAN_PLUGIN_DEFINE(name, description, version, init, exit) \
 		struct connman_plugin_desc connman_plugin_desc = { \
 			name, description, version, init, exit \
 		};
diff --git a/src/log.c b/src/log.c
index 93026d5..b195df2 100644
--- a/src/log.c
+++ b/src/log.c
@@ -30,6 +30,13 @@
 
 static volatile gboolean debug_enabled = FALSE;
 
+/**
+ * connman_info:
+ * @format: format string
+ * @Varargs: list of arguments
+ *
+ * Output general information
+ */
 void connman_info(const char *format, ...)
 {
 	va_list ap;
@@ -41,6 +48,13 @@ void connman_info(const char *format, ...)
 	va_end(ap);
 }
 
+/**
+ * connman_error:
+ * @format: format string
+ * @varargs: list of arguments
+ *
+ * Output error messages
+ */
 void connman_error(const char *format, ...)
 {
 	va_list ap;
@@ -52,6 +66,16 @@ void connman_error(const char *format, ...)
 	va_end(ap);
 }
 
+/**
+ * connman_debug:
+ * @format: format string
+ * @varargs: list of arguments
+ *
+ * Output debug message
+ *
+ * The actual output of the debug message is controlled via a command line
+ * switch. If not enabled, these messages will be ignored.
+ */
 void connman_debug(const char *format, ...)
 {
 	va_list ap;
diff --git a/src/plugin.c b/src/plugin.c
index d2ee80f..244aaeb 100644
--- a/src/plugin.c
+++ b/src/plugin.c
@@ -28,8 +28,6 @@
 #include <glib.h>
 #include <gmodule.h>
 
-#include <connman/plugin.h>
-
 #include "connman.h"
 
 static GSList *plugins = NULL;
-- 
2.7.4