jcarr
/
libnotify
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Port to gi-docgen 

Fixes: https://gitlab.gnome.org/GNOME/libnotify/-/issues/26
This commit is contained in:
Maximiliano Sandoval R 2022-07-14 18:27:50 +02:00
parent 359443f70f
commit 347dc44ee4
No known key found for this signature in database
GPG Key ID: D64A8D747F6FE706
15 changed files with 228 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/reference/libnotify-docs.sgml
View File

@ -1,30 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>Libnotify Reference Manual</title>
<releaseinfo>
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="http://developer.gnome.org/libnotify/unstable/">http://developer.gnome.org/libnotify/unstable/</ulink>.
</releaseinfo>
</bookinfo>
<chapter>
<title>Libnotify</title>
<xi:include href="xml/notify.xml"/>
<xi:include href="xml/notification.xml"/>
</chapter>
<index id="api-index-full">
<title id="index-all">Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="api-index-deprecated" role="deprecated">
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

0
docs/reference/libnotify-overrides.txt
View File

54
docs/reference/libnotify-sections.txt
View File

@ -1,54 +0,0 @@
<SECTION>
<FILE>notification</FILE>
NOTIFY_EXPIRES_DEFAULT
NOTIFY_EXPIRES_NEVER
<TITLE>NotifyNotification</TITLE>
NotifyNotification
NotifyClosedReason
NotifyUrgency
NotifyActionCallback
NOTIFY_ACTION_CALLBACK
notify_notification_new
notify_notification_update
notify_notification_show
notify_notification_set_app_name
notify_notification_set_timeout
notify_notification_set_category
notify_notification_set_urgency
notify_notification_set_icon_from_pixbuf
notify_notification_set_image_from_pixbuf
notify_notification_set_hint
notify_notification_set_hint_int32
notify_notification_set_hint_uint32
notify_notification_set_hint_double
notify_notification_set_hint_string
notify_notification_set_hint_byte
notify_notification_set_hint_byte_array
notify_notification_clear_hints
notify_notification_add_action
notify_notification_clear_actions
notify_notification_close
notify_notification_get_activation_token
notify_notification_get_closed_reason
<SUBSECTION Standard>
NotifyNotificationPrivate
NOTIFY_NOTIFICATION
NOTIFY_IS_NOTIFICATION
NOTIFY_TYPE_NOTIFICATION
notify_notification_get_type
NOTIFY_NOTIFICATION_CLASS
NOTIFY_IS_NOTIFICATION_CLASS
NOTIFY_NOTIFICATION_GET_CLASS
</SECTION>
<SECTION>
<FILE>notify</FILE>
notify_init
notify_uninit
notify_is_initted
notify_get_app_name
notify_set_app_name
notify_get_server_caps
notify_get_server_info
</SECTION>

44
docs/reference/libnotify.toml.in Normal file
View File

@ -0,0 +1,44 @@
[library]
version = "@VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/libnotify/"
repository_url = "https://gitlab.gnome.org/GNOME/libnotify.git"
website_url = "https://gitlab.gnome.org/GNOME/libnotify/"
docs_url = "https://gnome.pages.gitlab.gnome.org/libnotify/"
authors = "Marco Trevisan, Logan Rathbone, Christian Hammond, Mike Hearn, and John (J5) Palmieri"
license = "LGPL-2.1-or-later"
description = ""
dependencies = [ "GObject-2.0", "GLib-1.0", "Gio-2.0" ]
devhelp = true
search_index = true
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."GLib-2.0"]
name = "GLib"
description = "The base type system library"
docs_url = "https://docs.gtk.org/glib/"
[dependencies."Gio-2.0"]
name = "GIO"
description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
docs_url = "https://docs.gtk.org/gio/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[source-location]
base_url = "https://gitlab.gnome.org/GNOME/libnotify/-/blob/master"
[extra]
# The same order will be used when generating the index
content_files = [
]
content_images = [
]
urlmap_file = "urlmap.js"

3
docs/reference/libnotify.types
View File

@ -1,3 +0,0 @@
#include <libnotify/notify.h>
notify_notification_get_type

48
docs/reference/meson.build
View File

@ -1,10 +1,40 @@
gnome.gtkdoc(meson.project_name(),
mode: 'sgml',
main_sgml: meson.project_name() + '-docs.sgml',
src_dir: join_paths(meson.source_root(), meson.project_name()),
dependencies: libnotify_dep,
gobject_typesfile: meson.project_name() + '.types',
ignore_headers: ['notify-enum-types.h', 'notify-marshal.h', 'internal.h'],
scan_args: [ '--deprecated-guards=LIBNOTIFY_DISABLE_DEPRECATED' ],
install: true,
api_version_major = '0'
expand_content_md_files = []
toml_data = configuration_data()
toml_data.set('VERSION', meson.project_version())
libnotify_toml = configure_file(
input: 'libnotify.toml.in',
output: 'libnotify.toml',
configuration: toml_data
)
dependency('gi-docgen', version: '>= 2021.7',
fallback: ['gi-docgen', 'dummy_dep'],
native: true,
required: get_option('gtk_doc'))
gidocgen = find_program('gi-docgen')
docs_dir = get_option('datadir') / 'doc'
custom_target('libnotify-doc',
input: [ libnotify_toml, libnotify_gir[0] ],
output: 'libnotify-@0@'.format(api_version_major),
command: [
gidocgen,
'generate',
'--quiet',
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../libnotify'),
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--no-namespace-dir',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
depend_files: [ expand_content_md_files ],
build_by_default: true,
install: true,
install_dir: docs_dir,
)

7
docs/reference/urlmap.js Normal file
View File

@ -0,0 +1,7 @@
// A map between namespaces and base URLs for their online documentation
baseURLs = [
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],
[ 'Gio', 'https://docs.gtk.org/gio/' ],
["GdkPixbuf", "https://docs.gtk.org/gdk-pixbuf/"],
]

2
libnotify/meson.build
View File

@ -72,7 +72,7 @@ introspection = get_option('introspection')
g_ir_scanner = find_program('g-ir-scanner', required: introspection.enabled())
if g_ir_scanner.found() and not introspection.disabled()
gnome.generate_gir(libnotify_lib,
libnotify_gir = gnome.generate_gir(libnotify_lib,
sources: headers + sources + enum_types,
namespace: 'Notify',
nsversion: MODULE_VERSION,

127
libnotify/notification.c
View File

@ -30,9 +30,9 @@
/**
* SECTION:notification
* @Short_description: A passive pop-up notification.
* @Title: NotifyNotification
* NotifyNotification:
*
* A passive pop-up notification.
*
* #NotifyNotification represents a passive pop-up notification. It can
* contain summary text, body text, and an icon, as well as hints specifying
@ -173,6 +173,11 @@ notify_notification_class_init (NotifyNotificationClass *klass)
G_TYPE_NONE,
0);
/**
* NotifyNotification:id:
*
* The Id of the notification.
*/
g_object_class_install_property (object_class,
PROP_ID,
g_param_spec_int ("id", "ID",
@ -186,6 +191,13 @@ notify_notification_class_init (NotifyNotificationClass *klass)
| G_PARAM_STATIC_NICK
| G_PARAM_STATIC_BLURB));
/**
* NotifyNotification:app-name:
*
* The name of the application for the notification.
*
* Since: 0.7.3
*/
g_object_class_install_property (object_class,
PROP_APP_NAME,
g_param_spec_string ("app-name",
@ -197,6 +209,11 @@ notify_notification_class_init (NotifyNotificationClass *klass)
| G_PARAM_STATIC_NICK
| G_PARAM_STATIC_BLURB));
/**
* NotifyNotification:summary:
*
* The summary of the notification.
*/
g_object_class_install_property (object_class,
PROP_SUMMARY,
g_param_spec_string ("summary",
@ -209,6 +226,11 @@ notify_notification_class_init (NotifyNotificationClass *klass)
| G_PARAM_STATIC_NICK
| G_PARAM_STATIC_BLURB));
/**
* NotifyNotification:body:
*
* The body of the notification.
*/
g_object_class_install_property (object_class,
PROP_BODY,
g_param_spec_string ("body",
@ -221,6 +243,11 @@ notify_notification_class_init (NotifyNotificationClass *klass)
| G_PARAM_STATIC_NICK
| G_PARAM_STATIC_BLURB));
/**
* NotifyNotification:icon-name:
*
* The icon-name of the icon to be displayed on the notification.
*/
g_object_class_install_property (object_class,
PROP_ICON_NAME,
g_param_spec_string ("icon-name",
@ -233,6 +260,13 @@ notify_notification_class_init (NotifyNotificationClass *klass)
| G_PARAM_STATIC_NICK
| G_PARAM_STATIC_BLURB));
/**
* NotifyNotification:closed-reason:
*
* The closed reason of the notification.
*
* See [signal@Notification::closed].
*/
g_object_class_install_property (object_class,
PROP_CLOSED_REASON,
g_param_spec_int ("closed-reason",
@ -443,8 +477,9 @@ maybe_warn_portal_unsupported_feature (const char *feature_name)
* @body: (allow-none): The optional body text.
* @icon: (allow-none): The optional icon theme icon name or filename.
*
* Creates a new #NotifyNotification. The summary text is required, but
* all other parameters are optional.
* Creates a new #NotifyNotification.
*
* The summary text is required, but all other parameters are optional.
*
* Returns: The new #NotifyNotification.
*/
@ -601,9 +636,10 @@ notify_notification_update_internal (NotifyNotification *notification,
* @body: (allow-none): The optional body text.
* @icon: (allow-none): The optional icon theme icon name or filename.
*
* Updates the notification text and icon. This won't send the update out
* and display it on the screen. For that, you will need to call
* notify_notification_show().
* Updates the notification text and icon.
*
* This won't send the update out and display it on the screen. For that, you
* will need to call [method@Notification.show].
*
* Returns: %TRUE, unless an invalid parameter was passed.
*/
@ -1055,7 +1091,7 @@ add_portal_notification (GDBusProxy *proxy,
* Tells the notification server to display the notification on the screen.
*
* Returns: %TRUE if successful. On error, this will return %FALSE and set
* @error.
* @error.
*/
gboolean
notify_notification_show (NotifyNotification *notification,
@ -1179,9 +1215,10 @@ notify_notification_show (NotifyNotification *notification,
* @notification: The notification.
* @timeout: The timeout in milliseconds.
*
* Sets the timeout of the notification. To set the default time, pass
* %NOTIFY_EXPIRES_DEFAULT as @timeout. To set the notification to never
* expire, pass %NOTIFY_EXPIRES_NEVER.
* Sets the timeout of the notification.
*
* To set the default time, pass %NOTIFY_EXPIRES_DEFAULT as @timeout. To set the
* notification to never expire, pass %NOTIFY_EXPIRES_NEVER.
*
* Note that the timeout may be ignored by the server.
*/
@ -1209,8 +1246,10 @@ _notify_notification_get_timeout (const NotifyNotification *notification)
* @notification: The notification.
* @category: The category.
*
* Sets the category of this notification. This can be used by the
* notification server to filter or display the data in a certain way.
* Sets the category of this notification.
*
* This can be used by the notification server to filter or display the data in
* a certain way.
*/
void
notify_notification_set_category (NotifyNotification *notification,
@ -1236,8 +1275,6 @@ notify_notification_set_category (NotifyNotification *notification,
* @urgency: The urgency level.
*
* Sets the urgency level of this notification.
*
* See: #NotifyUrgency
*/
void
notify_notification_set_urgency (NotifyNotification *notification,
@ -1257,8 +1294,8 @@ notify_notification_set_urgency (NotifyNotification *notification,
* @icon: The icon.
*
* Sets the icon in the notification from a #GdkPixbuf.
* Deprecated: use notify_notification_set_image_from_pixbuf() instead.
*
* Deprecated: use [method@Notification.set_image_from_pixbuf] instead.
*/
void
notify_notification_set_icon_from_pixbuf (NotifyNotification *notification,
@ -1272,8 +1309,7 @@ notify_notification_set_icon_from_pixbuf (NotifyNotification *notification,
* @notification: The notification.
* @pixbuf: The image.
*
* Sets the image in the notification from a #GdkPixbuf.
*
* Sets the image in the notification from a [class@GdkPixbuf.Pixbuf].
*/
void
notify_notification_set_image_from_pixbuf (NotifyNotification *notification,
@ -1392,8 +1428,9 @@ maybe_parse_snap_hint_value (NotifyNotification *notification,
* @key: the hint key
* @value: (allow-none): the hint value, or %NULL to unset the hint
*
* Sets a hint for @key with value @value. If @value is %NULL,
* a previously set hint for @key is unset.
* Sets a hint for @key with value @value.
*
* If @value is %NULL, a previously set hint for @key is unset.
*
* If @value is floating, it is consumed.
*
@ -1422,10 +1459,11 @@ notify_notification_set_hint (NotifyNotification *notification,
* @notification: a #NotifyNotification
* @app_name: the localised application name
*
* Sets the application name for the notification. If this function is
* not called or if @app_name is %NULL, the application name will be
* set from the value used in notify_init() or overridden with
* notify_set_app_name().
* Sets the application name for the notification.
*
* If this function is not called or if @app_name is %NULL, the application name
* will be set from the value used in [func@init] or overridden with
* [func@set_app_name].
*
* Since: 0.7.3
*/
@ -1453,7 +1491,7 @@ notify_notification_set_app_name (NotifyNotification *notification,
*
* Sets a hint with a 32-bit integer value.
*
* Deprecated: 0.6. Use notify_notification_set_hint() instead
* Deprecated: 0.6. Use [method@Notification.set_hint] instead
*/
void
notify_notification_set_hint_int32 (NotifyNotification *notification,
@ -1473,7 +1511,7 @@ notify_notification_set_hint_int32 (NotifyNotification *notification,
*
* Sets a hint with an unsigned 32-bit integer value.
*
* Deprecated: 0.6. Use notify_notification_set_hint() instead
* Deprecated: 0.6. Use [method@Notification.set_hint] instead
*/
void
notify_notification_set_hint_uint32 (NotifyNotification *notification,
@ -1492,7 +1530,7 @@ notify_notification_set_hint_uint32 (NotifyNotification *notification,
*
* Sets a hint with a double value.
*
* Deprecated: 0.6. Use notify_notification_set_hint() instead
* Deprecated: 0.6. Use [method@Notification.set_hint] instead
*/
void
notify_notification_set_hint_double (NotifyNotification *notification,
@ -1511,7 +1549,7 @@ notify_notification_set_hint_double (NotifyNotification *notification,
*
* Sets a hint with a byte value.
*
* Deprecated: 0.6. Use notify_notification_set_hint() instead
* Deprecated: 0.6. Use [method@Notification.set_hint] instead
*/
void
notify_notification_set_hint_byte (NotifyNotification *notification,
@ -1529,10 +1567,11 @@ notify_notification_set_hint_byte (NotifyNotification *notification,
* @value: (array length=len): The hint's value.
* @len: The length of the byte array.
*
* Sets a hint with a byte array value. The length of @value must be passed
* as @len.
* Sets a hint with a byte array value.
*
* Deprecated: 0.6. Use notify_notification_set_hint() instead
* The length of @value must be passed as @len.
*
* Deprecated: 0.6. Use [method@Notification.set_hint] instead
*/
void
notify_notification_set_hint_byte_array (NotifyNotification *notification,
@ -1566,7 +1605,7 @@ notify_notification_set_hint_byte_array (NotifyNotification *notification,
*
* Sets a hint with a string value.
*
* Deprecated: 0.6. Use notify_notification_set_hint() instead
* Deprecated: 0.6. Use [method@Notification.set_hint] instead
*/
void
notify_notification_set_hint_string (NotifyNotification *notification,
@ -1638,11 +1677,12 @@ notify_notification_clear_actions (NotifyNotification *notification)
* @callback: The action's callback function.
* @user_data: Optional custom data to pass to @callback.
* @free_func: (type GLib.DestroyNotify): An optional function to free @user_data when the notification
* is destroyed.
* is destroyed.
*
* Adds an action to a notification. When the action is invoked, the
* specified callback function will be called, along with the value passed
* to @user_data.
* Adds an action to a notification.
*
* When the action is invoked, the specified callback function will be called,
* along with the value passed to @user_data.
*/
void
notify_notification_add_action (NotifyNotification *notification,
@ -1681,8 +1721,10 @@ notify_notification_add_action (NotifyNotification *notification,
* notify_notification_get_activation_token:
* @notification: The notification.
*
* Gets the activation token of the notification.
*
* If an an action is currently being activated, return the activation token.
* This function is intended to be used in a #NotifyActionCallback to get
* This function is intended to be used in a [callback@ActionCallback] to get
* the activation token for the activated action, if the notification daemon
* supports it.
*
@ -1762,13 +1804,14 @@ notify_notification_close (NotifyNotification *notification,
* notify_notification_get_closed_reason:
* @notification: The notification.
*
* Returns the closed reason code for the notification. This is valid only
* after the "closed" signal is emitted.
* Returns the closed reason code for the notification.
*
* Since version 0.8.0 the returned value is of type #NotifyClosedReason.
* This is valid only after the [signal@Notification::closed] signal is emitted.
*
* Since version 0.8.0 the returned value is of type [enum@ClosedReason].
*
* Returns: An integer representing the closed reason code
* (Since 0.8.0 it's also a #NotifyClosedReason).
* (Since 0.8.0 it's also a [enum@ClosedReason]).
*/
gint
notify_notification_get_closed_reason (const NotifyNotification *notification)

12
libnotify/notification.h
View File

@ -39,8 +39,9 @@ G_BEGIN_DECLS
/**
* NOTIFY_EXPIRES_NEVER:
*
* The notification never expires. It stays open until closed by the calling API
* or the user.
* The notification never expires.
*
* It stays open until closed by the calling API or the user.
*/
#define NOTIFY_EXPIRES_NEVER 0
@ -100,7 +101,7 @@ typedef enum
* @NOTIFY_CLOSED_REASON_EXPIRED: Timeout has expired.
* @NOTIFY_CLOSED_REASON_DISMISSED: It has been dismissed by the user.
* @NOTIFY_CLOSED_REASON_API_REQUEST: It has been closed by a call to
* notify_notification_close().
* [method@Notify.close].
* @NOTIFY_CLOSED_REASON_UNDEFIEND: Closed by undefined/reserved reasons.
*
* The reason for which the notification has been closed.
@ -132,8 +133,9 @@ typedef void (*NotifyActionCallback) (NotifyNotification *notification,
* NOTIFY_ACTION_CALLBACK:
* @func: The function to cast.
*
* A convenience macro for casting a function to a #NotifyActionCallback. This
* is much like G_CALLBACK().
* A convenience macro for casting a function to a [callback@ActionCallback].
*
* This is much like [func@GObject.CALLBACK].
*/
#define NOTIFY_ACTION_CALLBACK(func) ((NotifyActionCallback)(func))

26
libnotify/notify-features.h.in
View File

@ -23,12 +23,34 @@
/* compile time version
*/
/**
* NOTIFY_VERSION_MAJOR:
*
* Adwaita major version component (e.g. 1 if the version is 1.2.3).
*/
#define NOTIFY_VERSION_MAJOR (@LIBNOTIFY_MAJOR_VERSION@)
/**
* NOTIFY_VERSION_MINOR:
*
* Adwaita minor version component (e.g. 2 if the version is 1.2.3).
*/
#define NOTIFY_VERSION_MINOR (@LIBNOTIFY_MINOR_VERSION@)
/**
* NOTIFY_VERSION_MICRO:
*
* Adwaita micro version component (e.g. 3 if the version is 1.2.3).
*/
#define NOTIFY_VERSION_MICRO (@LIBNOTIFY_MICRO_VERSION@)
/* check whether a version equal to or greater than
* major.minor.micro is present.
/**
* NOTIFY_CHECK_VERSION:
* @major: required major version
* @minor: required minor version
* @micro: required micro version
*
* check whether a version equal to or greater than
* `major.minor.micro` is present.
*/
#define NOTIFY_CHECK_VERSION(major,minor,micro) \
(NOTIFY_VERSION_MAJOR > (major) || \

28
libnotify/notify.c
View File

@ -35,12 +35,6 @@
#include "internal.h"
#include "notify-marshal.h"
/**
* SECTION:notify
* @Short_description: Notification API
* @Title: notify
*/
static gboolean _initted = FALSE;
static char *_app_name = NULL;
static char *_snap_name = NULL;
@ -432,7 +426,7 @@ _notify_uses_portal_notifications (void)
*
* Gets the application name registered.
*
* Returns: The registered application name, passed to notify_init().
* Returns: The registered application name, passed to [func@init].
*/
const char *
notify_get_app_name (void)
@ -443,7 +437,7 @@ notify_get_app_name (void)
/**
* notify_uninit:
*
* Uninitialized libnotify.
* Uninitializes libnotify.
*
* This should be called when the program no longer needs libnotify for
* the rest of its lifecycle, typically just before exitting.
@ -592,10 +586,12 @@ out:
/**
* notify_get_server_caps:
*
* Synchronously queries the server for its capabilities and returns them in a #GList.
* Queries the server capabilities.
*
* Returns: (transfer full) (element-type utf8): a #GList of server capability strings. Free
* the list elements with g_free() and the list itself with g_list_free().
* Synchronously queries the server for its capabilities and returns them in a
* list.
*
* Returns: (transfer full) (element-type utf8): a list of server capability strings.
*/
GList *
notify_get_server_caps (void)
@ -654,12 +650,14 @@ notify_get_server_caps (void)
* @ret_version: (out) (allow-none) (transfer full): a location to store the server version, or %NULL
* @ret_spec_version: (out) (allow-none) (transfer full): a location to store the version the service is compliant with, or %NULL
*
* Synchronously queries the server for its information, specifically, the name, vendor,
* server version, and the version of the notifications specification that it
* is compliant with.
* Queries the server for information.
*
* Synchronously queries the server for its information, specifically, the name,
* vendor, server version, and the version of the notifications specification
* that it is compliant with.
*
* Returns: %TRUE if successful, and the variables passed will be set, %FALSE
* on error. The returned strings must be freed with g_free
* on error. The returned strings must be freed with g_free
*/
gboolean
notify_get_server_info (char **ret_name,

2
meson_options.txt
View File

@ -13,7 +13,7 @@ option('man',
option('gtk_doc',
type: 'boolean',
value: true,
description: 'Enable generating the API reference (depends on GTK-Doc)')
description: 'Enable generating the API reference (depends on gi-docgen)')
option('docbook_docs',
type: 'feature',
value: 'auto',

1
subprojects/gi-docgen Submodule

@ -0,0 +1 @@
Subproject commit 5ced0db97c1d38de83637d4e80749f35a1791bf1

6
subprojects/gi-docgen.wrap Normal file
View File

@ -0,0 +1,6 @@
[wrap-git]
directory=gi-docgen
url=https://gitlab.gnome.org/GNOME/gi-docgen.git
push-url=ssh://git@gitlab.gnome.org:GNOME/gi-docgen.git
revision=main
depth=1