luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-11 15:06:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Split out platform specific GIO and GLib documentation

Browse Source 
This creates `GioUnix`, `GioWin32`, `GLibUnix` and `GLibWin32`. These
bodies of documentation are in addition to the main, platform agnostic,
documentation for both libraries.

This commit necessarily includes various mechanical changes to update
the repository namespace used in various existing documentation links to
platform specific APIs.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
This commit is contained in:
Philip Withnall 2024-02-06 15:36:14 +00:00
parent 5021d002ab
commit c498c9a8c9
16 changed files with 363 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
docs/reference/gio/gio-unix.toml.in Normal file
View File

@ -0,0 +1,50 @@
# SPDX-License-Identifier: LGPL-2.1-or-later
# Copyright 2023 Matthias Clasen
# Copyright 2023 Philip Withnall
[library]
name = "GioUnix"
version = "@VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/glib/"
repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
website_url = "https://www.gtk.org"
docs_urls = "https://docs.gtk.org/gio-unix/"
authors = "GLib Development Team"
license = "LGPL-2.1-or-later"
description = "Unix-specific APIs in Gio"
dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0", "Gio-2.0" ]
devhelp = true
search_index = true
[dependencies."GLib-2.0"]
name = "GLib"
description = "The base utility library"
docs_url = "https://docs.gtk.org/glib/"
[dependencies."GModule-2.0"]
name = "GModule"
description = "Portable API for dynamically loading modules"
docs_url = "https://docs.gtk.org/gmodule/"
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."Gio-2.0"]
name = "Gio"
description = "A library of useful classes for I/O, networking and IPC"
docs_url = "https://docs.gtk.org/gio/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[extra]
urlmap_file = "../urlmap.js"
# The same order will be used when generating the index
content_files = [
"unix-mounts.md",
]
content_images = []

48
docs/reference/gio/gio-win32.toml.in Normal file
View File

@ -0,0 +1,48 @@
# SPDX-License-Identifier: LGPL-2.1-or-later
# Copyright 2023 Matthias Clasen
# Copyright 2023 Philip Withnall
[library]
name = "GioWin32"
version = "@VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/glib/"
repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
website_url = "https://www.gtk.org"
docs_urls = "https://docs.gtk.org/gio-win32/"
authors = "GLib Development Team"
license = "LGPL-2.1-or-later"
description = "Windows-specific APIs in Gio"
dependencies = [ "GLib-2.0", "GModule-2.0", "GObject-2.0", "Gio-2.0" ]
devhelp = true
search_index = true
[dependencies."GLib-2.0"]
name = "GLib"
description = "The base utility library"
docs_url = "https://docs.gtk.org/glib/"
[dependencies."GModule-2.0"]
name = "GModule"
description = "Portable API for dynamically loading modules"
docs_url = "https://docs.gtk.org/gmodule/"
[dependencies."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[dependencies."Gio-2.0"]
name = "Gio"
description = "A library of useful classes for I/O, networking and IPC"
docs_url = "https://docs.gtk.org/gio/"
[theme]
name = "basic"
show_index_summary = true
show_class_hierarchy = true
[extra]
urlmap_file = "../urlmap.js"
# The same order will be used when generating the index
content_files = []
content_images = []

1
docs/reference/gio/gio.toml.in
View File

@ -47,7 +47,6 @@ content_files = [
"error.md",
"pollable-utils.md",
"unix-mounts.md",
"dbus-error.md",
"dbus-introspection.md",

47
docs/reference/gio/meson.build
View File

@ -38,8 +38,11 @@ if get_option('documentation') and enable_gir
'overview.md',
'pollable-utils.md',
'tls-overview.md',
]
expand_content_unix_files = [
'unix-mounts.md',
]
expand_content_win32_files = []
gio_toml = configure_file(input: 'gio.toml.in', output: 'gio.toml', configuration: toml_conf)
@ -61,4 +64,48 @@ if get_option('documentation') and enable_gir
install_dir: docs_dir,
install_tag: 'doc',
)
if host_system == 'windows'
gio_win32_toml = configure_file(input: 'gio-win32.toml.in', output: 'gio-win32.toml', configuration: toml_conf)
custom_target('gio-win32-docs',
input: [ gio_win32_toml, gio_win32_gir[0] ],
output: 'gio-win32',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
build_by_default: true,
depend_files: expand_content_win32_files,
install: true,
install_dir: docs_dir,
install_tag: 'doc',
)
else
gio_unix_toml = configure_file(input: 'gio-unix.toml.in', output: 'gio-unix.toml', configuration: toml_conf)
custom_target('gio-unix-docs',
input: [ gio_unix_toml, gio_unix_gir[0] ],
output: 'gio-unix',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
build_by_default: true,
depend_files: expand_content_unix_files,
install: true,
install_dir: docs_dir,
install_tag: 'doc',
)
endif
endif

22
docs/reference/gio/migrating-posix.md
View File

@ -6,12 +6,16 @@ SPDX-FileCopyrightText: 2007 Matthias Clasen
## Comparison of POSIX and GIO concepts
| POSIX | GIO |
|-----------------------|-----------------------------------------------------|
| `char *path` | [iface@Gio.File] |
| `struct stat *buf` | [class@Gio.FileInfo] |
| `struct statvfs *buf` | [class@Gio.FileInfo] |
| `int fd` | [class@Gio.InputStream] or [class@Gio.OutputStream] |
| `DIR *` | [class@Gio.FileEnumerator] |
| `fstab entry` | [struct@Gio.UnixMountPoint] |
| `mtab entry` | [struct@Gio.UnixMountEntry] |
The final two entries in this table require including `gio-unix-2.0.pc` as well
as `gio-2.0.pc` in your build (or, in GIR namespace terms, `GioUnix-2.0` as well
as `Gio-2.0`).
| POSIX | GIO |
|-----------------------|-------------------------------------------------------------|
| `char *path` | [iface@Gio.File] |
| `struct stat *buf` | [class@Gio.FileInfo] |
| `struct statvfs *buf` | [class@Gio.FileInfo] |
| `int fd` | [class@Gio.InputStream] or [class@Gio.OutputStream] |
| `DIR *` | [class@Gio.FileEnumerator] |
| `fstab entry` | [`GUnixMountPoint`](../gio-unix/struct.UnixMountPoint.html) |
| `mtab entry` | [`GUnixMountEntry`](../gio-unix/struct.UnixMountEntry.html) |

26
docs/reference/gio/unix-mounts.md
View File

@ -13,23 +13,23 @@ file when using it.
There are three main classes:
* [struct@Gio.UnixMountEntry]
* [struct@Gio.UnixMountPoint]
* [class@Gio.UnixMountMonitor]
* [struct@GioUnix.UnixMountEntry]
* [struct@GioUnix.UnixMountPoint]
* [class@GioUnix.UnixMountMonitor]
Various helper functions for querying mounts:
* [func@Gio.unix_mount_points_get]
* [func@Gio.UnixMountPoint.at]
* [func@Gio.unix_mounts_get]
* [func@Gio.unix_mount_at]
* [func@Gio.unix_mount_for]
* [func@Gio.unix_mounts_changed_since]
* [func@Gio.unix_mount_points_changed_since]
* [func@GioUnix.unix_mount_points_get]
* [func@GioUnix.UnixMountPoint.at]
* [func@GioUnix.unix_mounts_get]
* [func@GioUnix.unix_mount_at]
* [func@GioUnix.unix_mount_for]
* [func@GioUnix.unix_mounts_changed_since]
* [func@GioUnix.unix_mount_points_changed_since]
And several helper functions for checking the type of a mount or path:
* [func@Gio.unix_is_mount_path_system_internal]
* [func@Gio.unix_is_system_fs_type]
* [func@Gio.unix_is_system_device_path]
* [func@GioUnix.unix_is_mount_path_system_internal]
* [func@GioUnix.unix_is_system_fs_type]
* [func@GioUnix.unix_is_system_device_path]

51
docs/reference/glib/glib-unix.toml.in Normal file
View File

@ -0,0 +1,51 @@
# SPDX-License-Identifier: LGPL-2.1-or-later
# Copyright 2023 Matthias Clasen
# Copyright 2023 Philip Withnall
[library]
name = "GLibUnix"
version = "@VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/glib/"
repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
website_url = "https://www.gtk.org"
docs_url = "https://docs.gtk.org/glib-unix/"
authors = "GLib Development Team"
license = "LGPL-2.1-or-later"
description = "Unix-specific APIs in GLib"
dependencies = [ "GLib-2.0" ]
related = [ "GModule-2.0", "GObject-2.0", "Gio-2.0" ]
devhelp = true
search_index = true
[dependencies."GLib-2.0"]
name = "GLib"
description = "The base utility library"
docs_url = "https://docs.gtk.org/glib/"
[related."GModule-2.0"]
name = "GModule"
description = "Portable API for dynamically loading modules"
docs_url = "https://docs.gtk.org/gmodule/"
[related."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[related."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
[extra]
urlmap_file = "../urlmap.js"
# The same order will be used when generating the index
content_files = [
"unix.md",
]
content_images = []

51
docs/reference/glib/glib-win32.toml.in Normal file
View File

@ -0,0 +1,51 @@
# SPDX-License-Identifier: LGPL-2.1-or-later
# Copyright 2023 Matthias Clasen
# Copyright 2023 Philip Withnall
[library]
name = "GLibWin32"
version = "@VERSION@"
browse_url = "https://gitlab.gnome.org/GNOME/glib/"
repository_url = "https://gitlab.gnome.org/GNOME/glib.git"
website_url = "https://www.gtk.org"
docs_url = "https://docs.gtk.org/glib-win32/"
authors = "GLib Development Team"
license = "LGPL-2.1-or-later"
description = "Windows-specific APIs in GLib"
dependencies = [ "GLib-2.0" ]
related = [ "GModule-2.0", "GObject-2.0", "Gio-2.0" ]
devhelp = true
search_index = true
[dependencies."GLib-2.0"]
name = "GLib"
description = "The base utility library"
docs_url = "https://docs.gtk.org/glib/"
[related."GModule-2.0"]
name = "GModule"
description = "Portable API for dynamically loading modules"
docs_url = "https://docs.gtk.org/gmodule/"
[related."GObject-2.0"]
name = "GObject"
description = "The base type system library"
docs_url = "https://docs.gtk.org/gobject/"
[related."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
[extra]
urlmap_file = "../urlmap.js"
# The same order will be used when generating the index
content_files = [
"windows.md",
]
content_images = []

2
docs/reference/glib/glib.toml.in
View File

@ -75,8 +75,6 @@ content_files = [
"checked-math.md",
"threads.md",
"spawn.md",
"unix.md",
"windows.md",
"random.md",
"numerical.md",
"markup.md",

50
docs/reference/glib/meson.build
View File

@ -91,10 +91,14 @@ if get_option('documentation') and enable_gir
'string-utils.md',
'types.md',
'unicode.md',
'unix.md',
'uuid.md',
'version.md',
'warnings.md',
]
expand_content_unix_files = [
'unix.md',
]
expand_content_win32_files = [
'windows.md',
]
@ -118,4 +122,48 @@ if get_option('documentation') and enable_gir
install_dir: docs_dir,
install_tag: 'doc',
)
if host_system == 'windows'
glib_win32_toml = configure_file(input: 'glib-win32.toml.in', output: 'glib-win32.toml', configuration: toml_conf)
custom_target('glib-win32-docs',
input: [ glib_win32_toml, glib_win32_gir[0] ],
output: 'glib-win32',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
build_by_default: true,
depend_files: expand_content_win32_files,
install: true,
install_dir: docs_dir,
install_tag: 'doc',
)
else
glib_unix_toml = configure_file(input: 'glib-unix.toml.in', output: 'glib-unix.toml', configuration: toml_conf)
custom_target('glib-unix-docs',
input: [ glib_unix_toml, glib_unix_gir[0] ],
output: 'glib-unix',
command: [
gidocgen,
'generate',
gidocgen_common_args,
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'@INPUT1@',
],
build_by_default: true,
depend_files: expand_content_unix_files,
install: true,
install_dir: docs_dir,
install_tag: 'doc',
)
endif
endif

20
docs/reference/glib/unix.md
View File

@ -14,12 +14,12 @@ To use these functions, you must explicitly include the
## File Descriptors
* [func@GLib.unix_open_pipe]
* [func@GLib.unix_set_fd_nonblocking]
* [func@GLibUnix.unix_open_pipe]
* [func@GLibUnix.unix_set_fd_nonblocking]
## Pipes
The [struct@GLib.UnixPipe] structure can be used to conveniently open and
The [struct@GLibUnix.UnixPipe] structure can be used to conveniently open and
manipulate a Unix pipe.
<!-- FIXME: https://gitlab.gnome.org/GNOME/gi-docgen/-/issues/173 -->
@ -33,16 +33,16 @@ The methods for it are all static inline for efficiency. They are:
## Signals
* [func@GLib.unix_signal_add]
* [func@GLib.unix_signal_add_full]
* [func@GLib.unix_signal_source_new]
* [func@GLibUnix.unix_signal_add]
* [func@GLibUnix.unix_signal_add_full]
* [func@GLibUnix.unix_signal_source_new]
## Polling
* [func@GLib.unix_fd_add]
* [func@GLib.unix_fd_add_full]
* [func@GLib.unix_fd_source_new]
* [func@GLibUnix.unix_fd_add]
* [func@GLibUnix.unix_fd_add_full]
* [func@GLibUnix.unix_fd_source_new]
## User Database
* [func@GLib.unix_get_passwd_entry]
* [func@GLibUnix.unix_get_passwd_entry]

26
docs/reference/glib/windows.md
View File

@ -8,19 +8,19 @@ These functions provide some level of Unix emulation on the
Windows platform. If your application really needs the POSIX
APIs, we suggest you try the [Cygwin project](https://cygwin.com/).
* [type@GLib.Win32OSType]
* [func@GLib.win32_check_windows_version]
* [func@GLib.win32_get_command_line]
* [func@GLib.win32_error_message]
* [func@GLib.win32_getlocale]
* [func@GLib.win32_get_package_installation_directory]
* [func@GLib.win32_get_package_installation_directory_of_module]
* [func@GLib.win32_get_package_installation_subdirectory]
* [func@GLib.win32_get_windows_version]
* [func@GLib.win32_locale_filename_from_utf8]
* [func@GLib.WIN32_HAVE_WIDECHAR_API]
* [func@GLib.WIN32_IS_NT_BASED]
* [type@GLibWin32.Win32OSType]
* [func@GLibWin32.win32_check_windows_version]
* [func@GLibWin32.win32_get_command_line]
* [func@GLibWin32.win32_error_message]
* [func@GLibWin32.win32_getlocale]
* [func@GLibWin32.win32_get_package_installation_directory]
* [func@GLibWin32.win32_get_package_installation_directory_of_module]
* [func@GLibWin32.win32_get_package_installation_subdirectory]
* [func@GLibWin32.win32_get_windows_version]
* [func@GLibWin32.win32_locale_filename_from_utf8]
* [func@GLibWin32.WIN32_HAVE_WIDECHAR_API]
* [func@GLibWin32.WIN32_IS_NT_BASED]
## Deprecated API
* [func@GLib.WIN32_DLLMAIN_FOR_DLL_NAME]
* [func@GLibWin32.WIN32_DLLMAIN_FOR_DLL_NAME]

4
docs/reference/urlmap.js
View File

@ -2,8 +2,12 @@
// SPDX-FileCopyrightText: 2023 Matthias Clasen
var baseURLs = [
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GLibUnix', 'https://docs.gtk.org/glib-unix/' ],
[ 'GLibWin32', 'https://docs.gtk.org/glib-win32/' ],
[ 'GModule', 'https://docs.gtk.org/gmodule/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],
[ 'Gio', 'https://docs.gtk.org/gio/' ],
[ 'GioUnix', 'https://docs.gtk.org/gio-unix/' ],
[ 'GioWin32', 'https://docs.gtk.org/gio-win32/' ],
[ 'Gtk', 'https://docs.gtk.org/gtk4/' ],
];

14
gio/gappinfo.c
View File

@ -1674,11 +1674,15 @@ g_app_launch_context_launch_failed (GAppLaunchContext *context,
* - [func@Gio.AppInfo.get_default_for_type]
* - [func@Gio.AppInfo.get_fallback_for_type]
* - [func@Gio.AppInfo.get_recommended_for_type]
* - [func@Gio.DesktopAppInfo.get_implementations]
* - [ctor@Gio.DesktopAppInfo.new]
* - [ctor@Gio.DesktopAppInfo.new_from_filename]
* - [ctor@Gio.DesktopAppInfo.new_from_keyfile]
* - [func@Gio.DesktopAppInfo.search]
* - [`g_desktop_app_info_get_implementations()`](../gio-unix/type_func.DesktopAppInfo.get_implementation.html)
* - [`g_desktop_app_info_new()`](../gio-unix/ctor.DesktopAppInfo.new.html)
* - [`g_desktop_app_info_new_from_filename()`](../gio-unix/ctor.DesktopAppInfo.new_from_filename.html)
* - [`g_desktop_app_info_new_from_keyfile()`](../gio-unix/ctor.DesktopAppInfo.new_from_keyfile.html)
* - [`g_desktop_app_info_search()`](../gio-unix/type_func.DesktopAppInfo.search.html)
*
* The latter functions are available if using
* [`GDesktopAppInfo`](../gio-unix/class.DesktopAppInfo.html) from
* `gio-unix-2.0.pc` (GIR namespace `GioUnix-2.0`).
*
* In the usual case, applications should try to make note of the change
* (doing things like invalidating caches) but not act on it. In

4
gio/gsimpleiostream.c
View File

@ -36,7 +36,9 @@
*
* This is useful when you obtained a [class@Gio.InputStream] and a
* [class@Gio.OutputStream] by other means, for instance creating them with
* platform specific methods as [ctor@Gio.UnixInputStream.new], and you want to
* platform specific methods as
* [`g_unix_input_stream_new()`](../gio-unix/ctor.UnixInputStream.new.html)
* (from `gio-unix-2.0.pc` / `GioUnix-2.0`), and you want to
* take advantage of the methods provided by [class@Gio.IOStream].
*
* Since: 2.44

3
gio/gunixfdlist.c
View File

@ -20,7 +20,8 @@
* A `GUnixFDList` contains a list of file descriptors. It owns the file
* descriptors that it contains, closing them when finalized.
*
* It may be wrapped in a [class@Gio.UnixFDMessage] and sent over a
* It may be wrapped in a
* [`GUnixFDMessage`](../gio-unix/class.UnixFDMessage.html) and sent over a
* [class@Gio.Socket] in the `G_SOCKET_FAMILY_UNIX` family by using
* [method@Gio.Socket.send_message] and received using
* [method@Gio.Socket.receive_message].