From a6d8f4bb835dc01344861e26b78867273322cb52 Mon Sep 17 00:00:00 2001 From: Marcel Holtmann 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. + + 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 #include -#include - #include "connman.h" static GSList *plugins = NULL; -- 2.7.4