Commit Graph

2961 Commits

Author SHA1 Message Date
0234f8e1b1 Merge branch 'ppd-api-rename' into 'main'
gio/powerprofilemonitordbus: Use newer D-Bus API

See merge request GNOME/glib!4478
2025-02-07 08:34:19 +00:00
236abac6fb gio/powerprofilemonitordbus: Use newer DBus API
Since some time the power-profiles-daemon project has been moved under
the upower umbrella and renamed its API to follow that.

While the legacy name is still supported, there are plans to not support
it anymore in future [2]. So let's update GLib code to use the
current main name instead.

[1] https://gitlab.freedesktop.org/upower/power-profiles-daemon/-/merge_requests/148
[2] https://gitlab.freedesktop.org/upower/power-profiles-daemon/-/merge_requests/166
2025-02-07 00:55:32 +01:00
cb1502ed66 docs: Fix invalid references and broken links
This commit fixes quite a few broken links and references, minor typos,
and improves wording in some sections.
2025-02-05 22:28:26 +02:00
58c4ab46f2 docs: Port GIO overview to gi-docgen linking syntax and fix a few typos
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2025-01-22 22:48:43 +00:00
d760bfef00 docs: Document more extension points
GIO is more extensible than we know! Document more of the existing
extension points, their included implementations and their purpose.
2025-01-21 12:00:42 +00:00
b65e950b3e docs: More gi-docgen linking in main-loop.md
Port the rest of the document to gi-docgen syntax, so we don’t have to
track partially-ported files.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3250
2025-01-13 17:47:12 +00:00
bd148fd04d docs: Use gi-docgen syntax in main-loop.md
The "Main Loop" documentation wasn't actually linking to `GMainContext`
properly, so let's fix this.
2025-01-12 15:33:19 +01:00
2ebd1c8f15 docs: Hide Unix and Win32 symbols from main GLib and GIO docs
These symbols are documented in the {glib,gio}-{unix,win32}
documentation builds, and shouldn’t be duplicated in the main
documentation. It’s a historical (and unavoidable) accident that those
symbols are in the main GIR files.

If we don’t hide the symbols from the main docs build, we now run into
the problem of the `GioUnix` namespace not being known to gi-docgen
while building the `Gio` docs. This is because of the previous two
commits, which ported more of the `gunixmounts` documentation to
gi-docgen syntax. I don’t know of another way to fix this, other than to
hide the `GioUnix` symbols from the `Gio` docs build.

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

Helps: #3250
2024-12-20 15:13:16 +00:00
2021e20a8a docs: Add --generate-md to the gdbus-codegen documentation
Add it to the documentation the same way it is done for reStructured and docbook.
2024-12-12 11:51:49 +00:00
e9670d3c3c docs: Warn if building documentation without enable_gir
If `-Ddocumentation=true` is specified without
`-Dintrospection=enabled`, warn the user. They might expect the
documentation to be built, but it won’t.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-12-11 15:36:50 +00:00
fa33e232d2 gio-tool: Clarify that gio mount -l only lists user-interesting things
It doesn’t list all mounts, only the ones you’d expect to see in a file
chooser sidebar.

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

Helps: #3555
2024-12-08 23:03:07 +00:00
8b29c53057 gmessages: Treat DEBUG_INVOCATION=1 same as G_MESSAGES_DEBUG=all
systemd 257 will now set `DEBUG_INVOCATION=1` in the execution context
of services which need to be debugged — for example if they’ve failed
and been restarted (and `RestartMode=debug`).

If we handle `DEBUG_INVOCATION=1` as being equivalent to
`G_MESSAGES_DEBUG=all`, then any processes using GLib’s default log
writer function (or `g_log_writer_default_would_drop()`) automatically
gains support for this feature.

See https://mastodon.social/@pid_eins/113548825942383777

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-11-27 16:10:22 +00:00
efab4c1c71 build: Bump the gi-docgen dependency to 2024.1
This gives us an updated enumeration template and link validation,
amongst other things.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-09-25 17:27:46 +01:00
ff00e9c2ed docs/gvariant: fix a(si) example in specification
This has a trailing 0x15 on it when you create it with GVariant and the
specification should match.

Closes: #3478
2024-09-24 09:22:52 -07:00
0bda424669 docs(glib): Fix link in string-utils ref 2024-09-12 06:04:34 -04:00
b4332b0056 docs: Clarify distinction between GDrive, GVolume and GMount
Provide examples of what they all represent, and expand on the
descriptions of them in a few places.

Move references to their equivalents from `GnomeVFS` to lower down in
the documentation, since `GnomeVFS` has been deprecated for many years
now, and is unlikely to be pertinent to most readers.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-08-15 11:32:37 +01:00
cc6f09f3f6 docs: Clarify an example in GObject concepts.md
Continue the existing example to make things more joined up and concrete.
2024-07-24 09:14:20 +00:00
35d76da8c8 docs: Clarify conventions about type naming and name mangling in GObject
These rules are not new, they’ve been around for a long time and are
needed to allow introspection machinery to be able to work reliably and
deterministically.

Unfortunately, they have not been documented canonically in one place
before.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-07-23 14:22:00 +02:00
a8b1e818f3 docs: Improve typesetting of GObject naming conventions slightly
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-07-22 18:56:04 +02:00
0b8f69b28a docs: Clarify that G_GNUC_UNUSED can’t be used on definitions
Only on declarations.

This has now bitten me multiple times.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-07-20 19:11:13 +02:00
a931a75c4f docs(GNode): Traversal diagrams, color & dark-mode
* Create a dark-mode variant of each traversal diagram, with the
  traversal path colorized `--primary` blue, instead of the original
  black.
* Apply the same colorizations to the light-mode diagrams, but
  using the light-theme `--primary` blue.
* Add SPDX license/copyright comments to all eight SVG files.
* Add new files to documentation configs in `glib.toml.in`.
* Update documentation comment in `gnode.c` to embed both color
  variants via picture tags, instead of markdown image embeds.
* Add alt text to all four images.
* Add additional blank lines to documentation comment, so that
  a. First item in bulleted list does not get folded into
     preceding intro paragraph
  b. Intro paragraph and diagrams are not part of first paragraph
     in documentation. (This also gets them out of the top-level
     table-of-contents/index list, where they previously appeared
     in full.)
* (Accidental change I didn't realize I was making): Convert line
  endings in breadth-first diagram from CRLF to LF.
2024-07-15 15:58:45 +00:00
a807604ef6 docs: Add source location URL
If the base URL for source location is set, gi-docgen will automatically
generate a link to the location of declarations and doc blocks in the
source.
2024-07-09 20:17:09 +01:00
f4d944119c Menu model example: Update diagram
- Add licensing tags
- Tweak spacing, colors, line thicknesses
- Create light-mode version
- Use `<picture>` tag to include appropriate version for each media
  color scheme.
2024-07-04 12:13:53 +01:00
85c8a7c0d8 Docs: Replace Gio.MenuModel diagram with SVG
Recreate the `menu-model.png` diagram in SVG, with box outlines and
connectors recolored from black to white. This will allow the diagram
to show up better in the dark documentation theme.
2024-07-04 12:13:53 +01:00
5bcc6ad458 Merge branch 'glib-compile-schemas-docs-1' into 'main'
docs: Mention XDG_DATA_HOME in glib-compile-schemas manual

See merge request GNOME/glib!4100
2024-06-03 10:56:41 +00:00
24dd331c2c Merge branch 'ebassi/issue-2896' into 'main'
Build HTML versions of the man pages

Closes #2896

See merge request GNOME/glib!4090
2024-06-02 15:15:31 +00:00
10fd218666 Build HTML versions of the man pages
And install them in the same directory as the API reference, so it's
possible to link them.

Fixes: #2896
2024-06-02 15:15:31 +00:00
b27e6b1a43 docs: Mention XDG_DATA_HOME in glib-compile-schemas manual
glib-compile-schemas considers XDG_DATA_HOME in addition to
XDG_DATA_DIRS since GLib 2.53.2, but this is not mentioned in its manual
and might bring confusion to readers.
2024-06-02 03:12:15 +08:00
c260521056 docs: Add and use anchors in conversion-macros
The documented conversion macros don't have their own page, so can't be
linked to directly.

Instead, introduce and use anchors for them.
2024-05-27 23:31:15 +02:00
f2df7c3115 docs: Add GTYPE_TO_POINTER/GPOINTER_TO_TYPE
Commit d0e03f09 introduced GTYPE_TO_POINTER/GPOINTER_TO_TYPE, on which
work started before the move of conversion macros to Markdown. It did
get merged after that move, but the macros never made it into the docs.

Let's do so now.
2024-05-27 23:24:42 +02:00
9b153495b6 docs: Improve conversion-macros formatting
There is no need to use double backticks. Also, insert extra newlines
between header and item, which paragraphs the item [1, 2], increading
readability by giving a little more "breathing" room between items. This
is also done in `macros.md`. Also, indentation of the definition block
should technically be 4 if extra paragraphs are needed, but it's better
to use 4 indentation always to prevent future problems after edits.

[1] https://python-markdown.github.io/extensions/definition_lists/
[2] https://michelf.ca/projects/php-markdown/extra/#def-list
2024-05-22 22:40:31 +02:00
af7c7c0495 Merge branch '3369-dead-links' into 'main'
docs: Fix broken links in gdbus-codegen documentation

Closes #3369

See merge request GNOME/glib!4086
2024-05-21 10:27:29 +00:00
066a2cd8cc docs: Fix broken links in gdbus-codegen documentation
Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Fixes: #3369
2024-05-20 13:50:46 +01:00
c068c1cd74 docs: Remove hex escape mention in gvariant-text-format bytestring
bytestring_parse does not actually support hexadecimal escape sequences.
2024-05-20 13:31:03 +01:00
460a9c299c docs: Adjust gvariant-text-format reference on bytestring escapes
- Do not refer to people’s expectation, they can wildly differ.
- Do not link to `strcompress`, that confusingly does not support `\a`. Link Wikipedia instead.
- Reiterate the C escape sequences from string section, they are not that many.
- Mention escaping newline and other characters (also copied from string section).
- Mention Unicode escapes not being supported to contrast with strings.
2024-05-19 00:55:45 +02:00
32b8a8400d docs: Link Wikipedia on C escapes in gvariant-text-format for strings
Unlike in the bytestring section there is no link to explanation.
2024-05-19 00:55:45 +02:00
56d8f14ab2 docs: Correct octal format in gvariant-text-format
There is no o or 0 prefix, just one to three octal numbers.
2024-05-19 00:31:25 +02:00
3807fae17e Fix consistency of code blocks
Use the appropriate code blocks for strings, file names,
and extensions.
2024-05-16 22:45:53 +01:00
91a08c01f3 Document the magic gettext macros in gi18n.h
These symbols are barely introspectable, which means they have to be
collected into the existing i18n content document.

Fixes: #3361
2024-05-16 22:45:53 +01:00
a8537918bc docs: Fix string-utils paragraph heading
Commit 425731f7 moved string utils docs to a Markdown file, but one of
the paragraph headings was left broken.
2024-05-15 12:07:44 +01:00
cd45ba8638 Correct installation directory of GVariant specification
548ec9f186 accidentally moved the GVariant
spec to the toplevel /usr/share/doc directory, which is surely not
right. Let's move it back into the glib-2.0 subdirectory.

It's debatable whether this is the best place to install the GVariant
specification, since it's not part of the gi-docgen docs, but surely
it's much better than not putting it in any subdirectory.

Fixes #3351
2024-05-07 14:24:38 -05:00
471bd469f1 docs(gio/overview): Restore missing heading 2024-04-21 23:03:54 +00:00
156e0c865a docs: Fix broken links
The file was renamed in 5d80471d4b.
2024-04-16 14:33:45 +01:00
4a1f1e3681 docs/variant-format: Clarify h type string
It was confusing that int32 was mentioned twice.
2024-04-16 11:41:13 +02:00
f94fc9da1c docs/gvariant-spec: Mention d and h type strings 2024-04-16 11:41:13 +02:00
b20647c2e2 docs: spelling and grammar fixes
Signed-off-by: Ville Skyttä <ville.skytta@iki.fi>
2024-04-01 11:01:06 +00:00
ed4f29cce8 gio: Change ‘unrecognised’ to ‘unrecognized’ in various user-visible places
The source language of GLib is technically en-US, so we should
consistently use en-US spellings.

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

Helps: #3269
2024-03-27 12:07:42 +00:00
ce39797fa3 Fix a typo 2024-03-27 17:37:55 +08:00
548ec9f186 docs: Reduce nesting of documentation directories
The `gi-docgen` tool is not designed to be used like that. In
particular, when nesting documentation directories, the generated
`*.devhelp2` files (needed by Devhelp to show the documentation) are
nested one directory level too deep for Devhelp to find them, and hence
are useless, and the documentation doesn’t show up in this common
documentation viewer.

So, change the installed documentation directory hierarchy:
 * `${PREFIX}/share/doc/glib-2.0/gio` → `${PREFIX}/share/doc/gio-2.0`
 * `${PREFIX}/share/doc/glib-2.0/glib-unix` →
   `${PREFIX}/share/doc/glib-unix-2.0`
 * `${PREFIX}/share/doc/glib-2.0/gobject` →
   `${PREFIX}/share/doc/gobject-2.0`
 * etc.
 * `${PREFIX}/share/doc/glib-2.0/glib` → `${PREFIX}/share/doc/glib-2.0`

This is going to seem like pointless churn (the contents of the
documentation have not changed), and packagers may mourn the split of
content in `/usr/share/doc` from `/usr/share/doc/${package_name}` to
`/usr/share/doc/${pkg_config_id}` instead, but that seems to be the best
approach to fix this issue in GLib. gi-docgen’s behaviour does feel
fairly consistent and correct with the rest of how it works (single
output directory).

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

Fixes: #3287
2024-03-13 18:51:21 +00:00
fafe1a14a8 docs: Minor reformatting / gi-docgenification of signals docs
This is nowhere near a complete check-through and gi-docgenification of
the signals docs, just a few bits I was looking at anyway.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Helps: #3250
2024-03-07 13:12:07 +00:00