From 09f40c836957fab37672d98fc6f3ca2611b94bbb Mon Sep 17 00:00:00 2001 From: Aleksander Morgado Date: Tue, 22 Nov 2011 11:33:35 +0100 Subject: docs: setup generation of gtk-doc based DBus API documentation It includes gdbus-codegen generated API documentation, plus the common Enums, Flags and Errors, which will also be used in libmm-glib. --- docs/reference/api/Makefile.am | 93 +++++++++++++++++++++++++ docs/reference/api/mm-docs.xml | 138 +++++++++++++++++++++++++++++++++++++ docs/reference/api/mm-overview.xml | 56 +++++++++++++++ docs/reference/api/mm-sections.txt | 32 +++++++++ docs/reference/api/mm.types | 0 docs/reference/api/version.xml.in | 1 + 6 files changed, 320 insertions(+) create mode 100644 docs/reference/api/Makefile.am create mode 100644 docs/reference/api/mm-docs.xml create mode 100644 docs/reference/api/mm-overview.xml create mode 100644 docs/reference/api/mm-sections.txt create mode 100644 docs/reference/api/mm.types create mode 100644 docs/reference/api/version.xml.in (limited to 'docs/reference/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@ -- cgit v1.2.3-70-g09d2