diff --git a/.gitignore b/.gitignore index d0c7ba18..55721d0c 100644 --- a/.gitignore +++ b/.gitignore @@ -12,6 +12,7 @@ ltmain.sh intltool-* missing stamp-h1 +gtk-doc.make *~ *.o *.lo @@ -61,6 +62,18 @@ po/insert-header.sin po/quot.sed po/remove-potcdate.sin +docs/reference/api/version.xml +docs/reference/api/mm.args +docs/reference/api/mm.hierarchy +docs/reference/api/mm.interfaces +docs/reference/api/mm.prerequisites +docs/reference/api/mm.signals +docs/reference/api/*.stamp +docs/reference/api/*.txt +docs/reference/api/html +docs/reference/api/tmpl +docs/reference/api/xml + m4/gtk-doc.m4 m4/intltool.m4 m4/libtool.m4 diff --git a/Makefile.am b/Makefile.am index 646df6dd..3dcecc27 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,5 +1,5 @@ -SUBDIRS = . marshallers build-aux include libmm-common libqcdm libwmc src plugins introspection po test +SUBDIRS = . marshallers build-aux include libmm-common libqcdm libwmc src plugins introspection po test docs if WITH_POLKIT SUBDIRS += policy diff --git a/autogen.sh b/autogen.sh index d99bad67..da0ab6be 100755 --- a/autogen.sh +++ b/autogen.sh @@ -14,6 +14,7 @@ PKG_NAME=ModemManager } (cd $srcdir; + gtkdocize || exit 1 autopoint --force AUTOPOINT='intltoolize --automake --copy' autoreconf --force --install --verbose if test -z "$NOCONFIGURE"; then diff --git a/configure.ac b/configure.ac index a73e863e..efd24244 100644 --- a/configure.ac +++ b/configure.ac @@ -21,6 +21,23 @@ dnl Initialize libtool LT_PREREQ([2.2]) LT_INIT +dnl +dnl Documentation +dnl + +AC_ARG_WITH(docs, AS_HELP_STRING([--with-docs], [Build ModemManager documentation])) +AM_CONDITIONAL(WITH_DOCS, test "x$with_docs" = "xyes") +case $with_docs in + yes) + enable_gtk_doc=yes + ;; + *) + with_docs=no + ;; +esac + +GTK_DOC_CHECK(1.0) + dnl dnl translation support dnl @@ -172,6 +189,10 @@ test/Makefile introspection/Makefile po/Makefile.in policy/Makefile +docs/Makefile +docs/reference/Makefile +docs/reference/api/Makefile +docs/reference/api/version.xml ]) AC_OUTPUT diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 00000000..cac25f2d --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,2 @@ + +SUBDIRS = reference diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am new file mode 100644 index 00000000..42627b5b --- /dev/null +++ b/docs/reference/Makefile.am @@ -0,0 +1,2 @@ + +SUBDIRS = api diff --git a/docs/reference/api/Makefile.am b/docs/reference/api/Makefile.am new file mode 100644 index 00000000..0c6c3866 --- /dev/null +++ b/docs/reference/api/Makefile.am @@ -0,0 +1,93 @@ + +# The name of the module. +DOC_MODULE = mm + +# The top-level SGML file. +DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml + +# Extra options to supply to gtkdoc-scan +SCAN_OPTIONS = + +# The directory containing the source code. +DOC_SOURCE_DIR = $(top_srcdir)/include + +HFILE_GLOB = +CFILE_GLOB = + +# Headers to ignore +IGNORE_HFILES = \ + ModemManager.h \ + ModemManager-names.h \ + $(NULL) + +# CFLAGS and LDFLAGS for compiling scan program. Only needed +# if $(DOC_MODULE).types is non-empty. +INCLUDES = \ + -I$(srcdir) \ + -I$(top_srcdir) \ + -I$(top_builddir) \ + $(MM_CFLAGS) \ + $(NULL) + +GTKDOC_LIBS = \ + $(MM_LIBS) \ + $(NULL) + +# Extra options to supply to gtkdoc-mkdb +MKDB_OPTIONS = --output-format=xml --sgml-mode --name-space=mm + +# Images to copy into HTML directory +HTML_IMAGES = \ + $(NULL) + +content_files = \ + $(NULL) + +expand_content_files = \ + mm-overview.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sim.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Sms.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Bearer.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Messaging.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Location.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Firmware.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Contacts.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Cdma.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.3gpp.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.3gpp.Ussd.xml \ + $(top_builddir)/libmm-common/mm-gdbus-doc-org.freedesktop.ModemManager1.Modem.Simple.xml \ + $(NULL) + +extra_files = \ + $(NULL) + +if ENABLE_GTK_DOC +include $(top_srcdir)/gtk-doc.make +else +EXTRA_DIST = +CLEANFILES = +endif + +EXTRA_DIST += \ + mm-overview.xml \ + version.xml.in \ + $(NULL) + +CLEANFILES += \ + $(DOC_MODULE)-decl-list.txt \ + $(DOC_MODULE)-decl.txt \ + $(DOC_MODULE)-overrides.txt \ + $(DOC_MODULE)-undeclared.txt \ + $(DOC_MODULE)-undocumented.txt \ + $(DOC_MODULE)-overrides.txt \ + $(DOC_MODULE)-unused.txt \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).interfaces \ + $(DOC_MODULE).prerequisites \ + $(DOC_MODULE).signals \ + *.stamp \ + -rf xml html tmpl \ + $(NULL) diff --git a/docs/reference/api/mm-docs.xml b/docs/reference/api/mm-docs.xml new file mode 100644 index 00000000..06e80565 --- /dev/null +++ b/docs/reference/api/mm-docs.xml @@ -0,0 +1,138 @@ + + +]> + + + ModemManager Reference Manual + Version &version; + + + 2008 + Novell, Inc. + + + 2008 + 2009 + 2010 + 2011 + Red Hat, Inc. + + + 2011 + The Chromium OS Authors + + + 2011 + Google, Inc. + + + + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free + Documentation License, Version 1.1 or any later + version published by the Free Software Foundation with no + Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. You may obtain a copy of the GNU Free + Documentation License from the Free Software + Foundation by visiting their Web site or by writing + to: +
+ 51 Franklin Street, Suite 500 + Boston, MA 02110-1335 + USA +
+ + + + + + + + D-Bus API Reference + + + Objects & Names + + The <literal>org.freedesktop.ModemManager1</literal> bus name + + The D-Bus name org.freedesktop.ModemManager1 + on the system bus is used by the ModemManager daemon. If this daemon + isn't running, it will be started if D-Bus messages are sent to the + name. + + + + + The <literal>/org/freedesktop/ModemManager</literal> + and <literal>/org/freedesktop/ModemManager/Modems</literal> objects + + + The ModemManager process will export an object at the well-known + path /org/freedesktop/ModemManager1. This object can + be used to list available modem objects, which will also be exposed + on paths with the folowing pattern + /org/freedesktop/ModemManager1/Modems/#. + + + + + + Common types + + + + + Manager interface + + + + SIM interface + + + + SMS interface + + + + Bearer interface + + + + Modem interfaces +
+ Generic + + +
+
+ 3GPP specific + + +
+
+ CDMA specific + +
+
+ Other + + + + +
+ + + + + Index + + + + Object Hierarchy + + + diff --git a/docs/reference/api/mm-overview.xml b/docs/reference/api/mm-overview.xml new file mode 100644 index 00000000..675acabe --- /dev/null +++ b/docs/reference/api/mm-overview.xml @@ -0,0 +1,56 @@ + + +]> + + ModemManager Overview + + + ModemManager + + ModemManager provides a unified high level API for communicating with + (mobile broadband) modems. While the basic commands are standardized, + the more advanced operations (like signal quality monitoring while + connected) varies a lot. + + + + Using + + ModemManager is a system daemon and is not meant to be used directly from + the command line. However, since it provides DBus API, it is possible to use + 'dbus-send' command to control it from the terminal. There's an example + program (tests/mm-test.py) that demonstrates the basic API usage. + + + + + Implementation + + ModemManager is a DBus system bus activated service (meaning it's started + automatically when a request arrives). It is written in C. The devices are + queried from udev and automatically updated based on hardware events. There's + a GInterface (MMModem) that defines the modem interface and any device specific + implementation must implement it. There are two generic MMModem implementations + to support the basic operations (one for GSM, one for CDMA,) which are common + for all cards. + + + + + Plugins + + Plugins are loaded on startup, and must implement the MMPlugin interface. It + consists of a couple of methods which tell the daemon whether the plugin + supports a port and to create custom MMModem implementations. It most likely + makes sense to derive custom modem implementations from one of the generic + classes and just add (or override) operations which are not standard. There's a + fully working plugin in the plugins/ directory for Huawei cards that can be + used as an example for writing new plugins. Writing new plugins is highly + encouraged! + + + + + diff --git a/docs/reference/api/mm-sections.txt b/docs/reference/api/mm-sections.txt new file mode 100644 index 00000000..329414dc --- /dev/null +++ b/docs/reference/api/mm-sections.txt @@ -0,0 +1,32 @@ +
+mm-enums +Flags and Enumerations +MMBearerIpMethod +MMModem3gppFacility +MMModem3gppNetworkAvailability +MMModem3gppRegistrationState +MMModem3gppUssdSessionState +MMModemAccessTech +MMModemBand +MMModemCapability +MMModemCdmaActivationError +MMModemCdmaActivationState +MMModemCdmaRegistrationState +MMModemContactsStorage +MMModemLocationSource +MMModemLock +MMModemMode +MMModemSmsState +MMModemState +MMModemStateChangeReason +
+ +
+mm-errors +Errors +MMConnectionError +MMCoreError +MMMessageError +MMMobileEquipmentError +MMSerialError +
diff --git a/docs/reference/api/mm.types b/docs/reference/api/mm.types new file mode 100644 index 00000000..e69de29b diff --git a/docs/reference/api/version.xml.in b/docs/reference/api/version.xml.in new file mode 100644 index 00000000..d78bda93 --- /dev/null +++ b/docs/reference/api/version.xml.in @@ -0,0 +1 @@ +@VERSION@