diff --git a/configure.ac b/configure.ac index b4af82792..e34db8e3e 100644 --- a/configure.ac +++ b/configure.ac @@ -213,6 +213,7 @@ data/tests/colorhug/Makefile data/tests/dfu/Makefile docs/Makefile docs/libdfu/Makefile +docs/libfwupd/Makefile docs/man/Makefile policy/Makefile po/Makefile.in diff --git a/contrib/fwupd.spec.in b/contrib/fwupd.spec.in index 72ba30591..347bef917 100644 --- a/contrib/fwupd.spec.in +++ b/contrib/fwupd.spec.in @@ -125,6 +125,7 @@ make check VERBOSE=1 %files devel %{_datadir}/gir-1.0/Fwupd-1.0.gir +%{_datadir}/gtk-doc/html/libfwupd %{_includedir}/fwupd-1 %{_libdir}/libfwupd*.so %{_libdir}/pkgconfig/fwupd.pc diff --git a/docs/Makefile.am b/docs/Makefile.am index 7ffa88b33..1603f0e9c 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,5 +1,6 @@ SUBDIRS = \ libdfu \ + libfwupd \ man EXTRA_DIST = \ diff --git a/docs/libdfu/clean.sh b/docs/libdfu/clean.sh index b74c48f5c..8d464940f 100755 --- a/docs/libdfu/clean.sh +++ b/docs/libdfu/clean.sh @@ -1,6 +1,4 @@ rm -f *.txt -rm -f colord-scan* -rm -f colord.types rm -rf html/ rm -rf xml/ rm -rf tmpl/ diff --git a/docs/libfwupd/Makefile.am b/docs/libfwupd/Makefile.am new file mode 100644 index 000000000..04f3d4b36 --- /dev/null +++ b/docs/libfwupd/Makefile.am @@ -0,0 +1,95 @@ +# This is a blank Makefile.am for using gtk-doc. +# Copy this to your project's API docs directory and modify the variables to +# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples +# of using the various options. + +# The name of the module, e.g. 'glib'. +DOC_MODULE=libfwupd + +# Uncomment for versioned docs and specify the version of the module, e.g. '2'. +#DOC_MODULE_VERSION=2 + +# The top-level XML file. +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml + +# Directories containing the source code. +# gtk-doc will search all .c and .h files beneath these paths +# for inline comments documenting functions and macros. +# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk +DOC_SOURCE_DIR=$(top_srcdir)/libfwupd + +# Extra options to pass to gtkdoc-scangobj. Normally not needed. +SCANGOBJ_OPTIONS= + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS= + +# Extra options to supply to gtkdoc-mkdb +# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml +MKDB_OPTIONS=--xml-mode --output-format=xml + +# Extra options to supply to gtkdoc-mkhtml +MKHTML_OPTIONS= + +# Extra options to supply to gtkdoc-fixref. Normally not needed. +# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +FIXXREF_OPTIONS= + +# Used for dependencies. The docs will be rebuilt if any of these change. +# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h +# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c +HFILE_GLOB=$(top_srcdir)/libfwupd/*.h +CFILE_GLOB=$(top_srcdir)/libfwupd/*.c + +# Extra header to include when scanning, which are not under DOC_SOURCE_DIR +# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h +EXTRA_HFILES= + +# Header files or dirs to ignore when scanning. Use base file/dir names +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code +IGNORE_HFILES= \ + fwupd-enums-private.h + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +HTML_IMAGES= + +# Extra files that are included by $(DOC_MAIN_SGML_FILE). +# e.g. content_files=running.xml building.xml changes-2.0.xml +content_files= + +# Files where gtk-doc abbrevations (#GtkWidget) are expanded +# e.g. expand_content_files=running.xml +expand_content_files= + +# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. +# Only needed if you are using gtkdoc-scangobj to dynamically query widget +# signals and properties. +# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +GTKDOC_CFLAGS= +GTKDOC_LIBS=$(top_builddir)/libfwupd/libfwupd.la + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/gtk-doc.make + +# Comment this out if you want 'make check' to test you doc status +# and run some sanity checks +#if ENABLE_GTK_DOC +#TESTS_ENVIRONMENT = \ +# DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ +# SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) +#TESTS = $(GTKDOC_CHECK) +#endif + +CLEANFILES= \ + libfwupd.args \ + libfwupd.hierarchy \ + libfwupd.interfaces \ + libfwupd.prerequisites \ + libfwupd.signals \ + libfwupd-*.txt \ + *.stamp + +-include $(top_srcdir)/git.mk diff --git a/docs/libfwupd/clean.sh b/docs/libfwupd/clean.sh new file mode 120000 index 000000000..533ca1666 --- /dev/null +++ b/docs/libfwupd/clean.sh @@ -0,0 +1 @@ +../libdfu/clean.sh \ No newline at end of file diff --git a/docs/libfwupd/libfwupd-docs.xml b/docs/libfwupd/libfwupd-docs.xml new file mode 100644 index 000000000..7d4afce52 --- /dev/null +++ b/docs/libfwupd/libfwupd-docs.xml @@ -0,0 +1,55 @@ + + +]> + + + libfwupd Reference Manual + + for libfwupd [VERSION]. + + + + + About libfwupd + + + libfwupd is a library for querying the fwupd daemon. + + + + + + Object Hierarchy + + + + + libfwupd + + + Functionality exported by libfwupd. + + + + + + + + + + + API Index + + + + + + + Index of deprecated API + + + + diff --git a/docs/libfwupd/libfwupd.types b/docs/libfwupd/libfwupd.types new file mode 100644 index 000000000..f6b640b12 --- /dev/null +++ b/docs/libfwupd/libfwupd.types @@ -0,0 +1,2 @@ +fwupd_client_get_type +fwupd_result_get_type diff --git a/libfwupd/fwupd-client.c b/libfwupd/fwupd-client.c index 7dc011f1e..48be1246b 100644 --- a/libfwupd/fwupd-client.c +++ b/libfwupd/fwupd-client.c @@ -877,7 +877,7 @@ fwupd_client_class_init (FwupdClientClass *klass) object_class->set_property = fwupd_client_set_property; /** - * AsStore::changed: + * FwupdClient::changed: * @client: the #FwupdClient instance that emitted the signal * * The ::changed signal is emitted when the daemon internal has @@ -893,7 +893,7 @@ fwupd_client_class_init (FwupdClientClass *klass) G_TYPE_NONE, 0); /** - * AsStore::state-changed: + * FwupdClient::state-changed: * @client: the #FwupdClient instance that emitted the signal * @status: the #FwupdStatus * @@ -911,6 +911,10 @@ fwupd_client_class_init (FwupdClientClass *klass) /** * FwupdClient:status: + * + * The last-reported status of the daemon. + * + * Since: 0.7.0 */ pspec = g_param_spec_uint ("status", NULL, NULL, 0, FWUPD_STATUS_LAST, FWUPD_STATUS_UNKNOWN, diff --git a/libfwupd/fwupd-enums.c b/libfwupd/fwupd-enums.c index a0964e698..bc7987a96 100644 --- a/libfwupd/fwupd-enums.c +++ b/libfwupd/fwupd-enums.c @@ -25,6 +25,11 @@ /** * fwupd_status_to_string: + * @status: A #FwupdStatus, e.g. %FWUPD_STATUS_DECOMPRESSING + * + * Converts a #FwupdStatus to a string. + * + * Return value: identifier string * * Since: 0.1.1 **/ @@ -52,6 +57,11 @@ fwupd_status_to_string (FwupdStatus status) /** * fwupd_status_from_string: + * @status: A string, e.g. "decompressing" + * + * Converts a string to a #FwupdStatus. + * + * Return value: enumerated value * * Since: 0.1.1 **/ @@ -79,6 +89,11 @@ fwupd_status_from_string (const gchar *status) /** * fwupd_device_flag_to_string: + * @device_flag: A #FwupdDeviceFlags, e.g. %FU_DEVICE_FLAG_REQUIRE_AC + * + * Converts a #FwupdDeviceFlags to a string. + * + * Return value: identifier string * * Since: 0.7.0 **/ @@ -102,6 +117,11 @@ fwupd_device_flag_to_string (FwupdDeviceFlags device_flag) /** * fwupd_device_flag_from_string: + * @device_flag: A string, e.g. "require-ac" + * + * Converts a string to a #FwupdDeviceFlags. + * + * Return value: enumerated value * * Since: 0.7.0 **/ @@ -125,6 +145,11 @@ fwupd_device_flag_from_string (const gchar *device_flag) /** * fwupd_update_state_to_string: + * @update_state: A #FwupdUpdateState, e.g. %FWUPD_UPDATE_STATE_PENDING + * + * Converts a #FwupdUpdateState to a string. + * + * Return value: identifier string * * Since: 0.7.0 **/ @@ -144,6 +169,11 @@ fwupd_update_state_to_string (FwupdUpdateState update_state) /** * fwupd_update_state_from_string: + * @update_state: A string, e.g. "pending" + * + * Converts a string to a #FwupdUpdateState. + * + * Return value: enumerated value * * Since: 0.7.0 **/ @@ -163,6 +193,11 @@ fwupd_update_state_from_string (const gchar *update_state) /** * fwupd_trust_flag_to_string: + * @trust_flag: A #FwupdTrustFlags, e.g. %FWUPD_TRUST_FLAG_PAYLOAD + * + * Converts a #FwupdTrustFlags to a string. + * + * Return value: identifier string * * Since: 0.7.0 **/ @@ -180,6 +215,11 @@ fwupd_trust_flag_to_string (FwupdTrustFlags trust_flag) /** * fwupd_trust_flag_from_string: + * @trust_flag: A string, e.g. "payload" + * + * Converts a string to a #FwupdTrustFlags. + * + * Return value: enumerated value * * Since: 0.7.0 **/ diff --git a/libfwupd/fwupd-enums.h b/libfwupd/fwupd-enums.h index 31af1e24e..100d136ab 100644 --- a/libfwupd/fwupd-enums.h +++ b/libfwupd/fwupd-enums.h @@ -32,6 +32,14 @@ /** * FwupdStatus: + * @FWUPD_STATUS_UNKNOWN: Unknown state + * @FWUPD_STATUS_IDLE: Idle + * @FWUPD_STATUS_LOADING: Loading a resource + * @FWUPD_STATUS_DECOMPRESSING: Decompressing firmware + * @FWUPD_STATUS_DEVICE_RESTART: Restarting the device + * @FWUPD_STATUS_DEVICE_WRITE: Writing to a device + * @FWUPD_STATUS_DEVICE_VERIFY: Verifying (reading) a device + * @FWUPD_STATUS_SCHEDULING: Scheduling an offline update * * The flags to show daemon status. **/ @@ -44,12 +52,15 @@ typedef enum { FWUPD_STATUS_DEVICE_WRITE, /* Since: 0.1.1 */ FWUPD_STATUS_DEVICE_VERIFY, /* Since: 0.1.1 */ FWUPD_STATUS_SCHEDULING, /* Since: 0.1.1 */ - /* private */ + /*< private >*/ FWUPD_STATUS_LAST } FwupdStatus; /** * FwupdTrustFlags: + * @FWUPD_TRUST_FLAG_NONE: No trust + * @FWUPD_TRUST_FLAG_PAYLOAD: The firmware is trusted + * @FWUPD_TRUST_FLAG_METADATA: The metadata is trusted * * The flags to show the level of trust. **/ @@ -57,12 +68,18 @@ typedef enum { FWUPD_TRUST_FLAG_NONE = 0, /* Since: 0.1.2 */ FWUPD_TRUST_FLAG_PAYLOAD = 1 << 0, /* Since: 0.1.2 */ FWUPD_TRUST_FLAG_METADATA = 1 << 1, /* Since: 0.1.2 */ - /* private */ + /*< private >*/ FWUPD_TRUST_FLAG_LAST } FwupdTrustFlags; /** * FwupdDeviceFlags: + * @FU_DEVICE_FLAG_NONE: No flags set + * @FU_DEVICE_FLAG_INTERNAL: Device cannot be removed easily + * @FU_DEVICE_FLAG_ALLOW_ONLINE: Permits 'live' updating + * @FU_DEVICE_FLAG_ALLOW_OFFLINE: Permits 'offline' updating + * @FU_DEVICE_FLAG_REQUIRE_AC: Requires AC power + * @FU_DEVICE_FLAG_LOCKED: Is locked and can be unlocked * * FIXME: rename FU_DEVICE_ -> FWUPD_DEVICE_ when we break API * @@ -75,12 +92,16 @@ typedef enum { FU_DEVICE_FLAG_ALLOW_OFFLINE = 1 << 2, /* Since: 0.1.3 */ FU_DEVICE_FLAG_REQUIRE_AC = 1 << 3, /* Since: 0.6.3 */ FU_DEVICE_FLAG_LOCKED = 1 << 4, /* Since: 0.6.3 */ - /* private */ + /*< private >*/ FU_DEVICE_FLAG_LAST } FwupdDeviceFlags; /** * FwupdInstallFlags: + * @FWUPD_INSTALL_FLAG_NONE: No flags set + * @FWUPD_INSTALL_FLAG_OFFLINE: Perform this offline + * @FWUPD_INSTALL_FLAG_ALLOW_REINSTALL: Allow reinstalling the same version + * @FWUPD_INSTALL_FLAG_ALLOW_OLDER: Allow downgrading firmware * * Flags to set when performing the firwmare update or install. **/ @@ -89,12 +110,16 @@ typedef enum { FWUPD_INSTALL_FLAG_OFFLINE = 1, /* Since: 0.7.0 */ FWUPD_INSTALL_FLAG_ALLOW_REINSTALL = 2, /* Since: 0.7.0 */ FWUPD_INSTALL_FLAG_ALLOW_OLDER = 4, /* Since: 0.7.0 */ - /* private */ + /*< private >*/ FWUPD_INSTALL_FLAG_LAST } FwupdInstallFlags; /** * FwupdUpdateState: + * @FWUPD_UPDATE_STATE_UNKNOWN: Unknown + * @FWUPD_UPDATE_STATE_PENDING: Update is pending + * @FWUPD_UPDATE_STATE_SUCCESS: Update was successfull + * @FWUPD_UPDATE_STATE_FAILED: Update failed * * The update state. **/ @@ -103,7 +128,7 @@ typedef enum { FWUPD_UPDATE_STATE_PENDING, /* Since: 0.7.0 */ FWUPD_UPDATE_STATE_SUCCESS, /* Since: 0.7.0 */ FWUPD_UPDATE_STATE_FAILED, /* Since: 0.7.0 */ - /* private */ + /*< private >*/ FWUPD_UPDATE_STATE_LAST } FwupdUpdateState; diff --git a/libfwupd/fwupd-result.c b/libfwupd/fwupd-result.c index 3b8dc3d7f..43fbdad7c 100644 --- a/libfwupd/fwupd-result.c +++ b/libfwupd/fwupd-result.c @@ -1694,6 +1694,10 @@ fwupd_result_class_init (FwupdResultClass *klass) /** * FwupdResult:device-id: + * + * The device ID for this result. + * + * Since: 0.7.0 */ pspec = g_param_spec_string ("device-id", NULL, NULL, NULL, diff --git a/libfwupd/fwupd-version.h.in b/libfwupd/fwupd-version.h.in index 33e734e27..b77e8357b 100644 --- a/libfwupd/fwupd-version.h.in +++ b/libfwupd/fwupd-version.h.in @@ -57,6 +57,9 @@ /** * FWUPD_CHECK_VERSION: + * @major: Major version number + * @minor: Minor version number + * @micro: Micro version number * * Check whether a fwupd version equal to or greater than * major.minor.micro.