Commit Graph

647 Commits

Author SHA1 Message Date
Philip Withnall
4c178fa623 build: Combine duplicate urlmap.js files
Seems no point in keeping them separate. It doesn’t seem to matter if
they contain entries which are unused for a particular docs build.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
2024-02-12 17:54:10 +00:00
Simon McVittie
aa28326b87 docs: Allow building man pages without the reference documentation
Now that the reference documentation uses gi-docgen, it's more
troublesome to generate in less standard build scenarios like
cross-compiling.

In distributions like Debian, reference documentation is generally
packaged separately (in libglib2.0-doc in Debian's case), but man pages
are generally packaged alongside the executables themselves (in the
libglib2.0-bin and libglib2.0-dev-bin packages, in Debian's case). We
can exclude the reference documentation when cross-compiling, but ideally
we would like the man pages to still be built, so that a cross-compiled
libglib2.0-bin or libglib2.0-dev-bin package has the same content as a
native build.

Signed-off-by: Simon McVittie <smcv@debian.org>
2024-01-11 15:41:34 +00:00
Emmanuele Bassi
0db7395ef9 build: Tell gi-docgen where to find the GIR files
Now that all files are located under top_srcdir/introspection, we need
to ensure that gi-docgen can find them.
2023-12-27 16:00:06 +00:00
Emmanuele Bassi
cda15952dd Merge branch '3037-install-docs' into 'main'
docs: Install the gi-docgen docs

See merge request GNOME/glib!3787
2023-12-21 18:23:53 +00:00
Philip Withnall
d2dbfba208 docs: Install the gi-docgen docs
They are now installed to (e.g.)
`${prefix}/share/doc/glib-2.0/{glib,gmodule,gobject,gio}/index.html`.

We might want to drop one level of nesting out of that, but for the
moment I thought I’d keep it in so we can disambiguate by installed
major version.

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

Helps: #3037
2023-12-21 17:00:06 +00:00
Philip Withnall
031e65808d docs: Port the man pages from DocBook to reStructuredText
So they are consistent with the way we’re building man pages in other
projects, and because some people are allergic to XML.

This changes the build-time dependencies from `xsltproc` to `rst2man`,
and also takes the opportunity to change the `-Dman` Meson option from a
boolean to a feature (so you should use `-Dman-pages={enabled,disabled}`
now, rather than `-Dman={true,false}`).

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

Helps: #3037
2023-12-21 13:34:48 +00:00
Philip Withnall
9ea0b6edf5 docs: Set install_tag on man pages
Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2023-12-18 14:52:39 +00:00
madmurphy
abd7f9863d Documentation only: Added clarification about GWeakNotify and removed ambiguous text 2023-12-03 22:48:46 +00:00
Philip Withnall
7b2ac3c82e docs: Consistently capitalise page titles
Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
2023-11-29 12:13:13 +00:00
Matthias Clasen
6ca2934928 build: Remove all remaining gtk-doc build infrastructure
It’s no longer needed: the documentation is built by gi-docgen now.

Fixes: #3037
2023-11-28 13:52:35 +00:00
Philip Withnall
0fe3a9d1df docs: Drop the tools tutorial page
It’s completely out of date.

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

Helps: #3037
2023-11-28 13:52:05 +00:00
Alexander Slobodeniuk
7880d87091 gvalue: add g_value_steal_string()
This call is needed to avoid an extra copy after
serialization of the data.
2023-11-04 10:40:30 +00:00
Emmanuele Bassi
3dbef3223b build: Fix the inclusion paths for GIR files in gi-docgen
The GIR files are now built by GLib itself, so they will be in the build
directories of each sub-library, except for GLib-2.0 which is built
alongside GObject-2.0.
2023-11-02 11:22:06 +00:00
Alex Richardson
d0e03f0930 GType: introduce GTYPE_TO_POINTER/GPOINTER_TO_TYPE
On CHERI-enabled systems we use uintptr_t as the underlying storage for
GType and therefore casting to gsize strips the upper bits from a pointer.
Fix this by casting via uintptr_t instead and introduce a new set of
macros to convert between GType and pointers.
2023-10-25 12:01:02 +01:00
Philip Withnall
5ae6bcb728 docs: Move the value collection documentation to Markdown
It needs to be in a separate page because it’s all macros and they have
no type/class associated with them.

Signed-off-by: Philip Withnall <philip@tecnocode.co.uk>

Helps: #3037
2023-10-23 13:18:13 +01:00
Emmanuele Bassi
160e5db742 Remove old introspection data
We don't need it any more.
2023-10-23 11:26:53 +01:00
Emmanuele Bassi
3ffa33825b Build the API references with the generated GIR data
Gate the API reference on the availability of the introspection data as
well, so we don't accidentally try and generate the documentation
without a description of our API.
2023-10-23 11:26:53 +01:00
Matthias Clasen
95717eacea docs: Move the signal SECTION
Move the content to the new signals.md file.

Helps: #3037
2023-10-16 23:34:35 +01:00
Matthias Clasen
f3eac349f9 docs: Move the GType SECTION
Move the contents to the new types.md files.

Helps: #3037
2023-10-16 23:34:29 +01:00
Matthias Clasen
3d55be0b82 docs: Move the GObject tutorial to Markdown
Helps: #3037
2023-10-11 14:01:29 +01:00
Matthias Clasen
0d05b87b9f docs: Move GObject concepts/intro to Markdown
Helps: #3037
2023-10-11 14:01:29 +01:00
Matthias Clasen
4411023462 docs: Move GValue documentation to Markdown
Helps: #3037
2023-10-11 14:01:29 +01:00
Matthias Clasen
e298f1a078 docs: Move floating refs documentation to Markdown
And add some new sections on strategies for avoiding designing APIs
around floating refs.

Helps: #3037
2023-10-11 14:01:29 +01:00
Matthias Clasen
58019515d6 docs: Move enum type documentation to Markdown
Helps: #3037
2023-10-11 14:01:29 +01:00
Matthias Clasen
24e93078d3 docs: Move boxed type documentation to Markdown
And add some additional new content and examples.

Helps: #3037
2023-10-11 14:01:29 +01:00
Philip Withnall
6107f50cc7 build: Disable gtk-doc unit tests
As we start moving documentation over from gtk-doc to gi-docgen, the
gtk-doc coverage is going to go down and things are going to start
breaking. That’s OK; we don’t need to test it any more.

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

Helps: #3037
2023-10-11 14:01:28 +01:00
Matthias Clasen
39e9ef54be docs: Add initial support for using gi-docgen for docs
The files here are copied from the docs-gtk-org
branch of gtk.

This adds gi-docgen to the CI Dockerfiles and ensures the new versions
(including the OS upgrades from the previous commit) are used during CI.

Helps: #3037
2023-10-11 14:01:28 +01:00
Philip Withnall
3a1e53b80d docs: Add 2.80 release series documentation pages to the build
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
2023-10-03 10:24:19 +01:00
Emmanuele Bassi
23a9dbdaf6 Allow proper introspection of GTypeValueTable
The introspection scanner cannot deal very well with function pointers
into a plain structure. In order to document the various function
pointers in GTypeValueTable we need to create typed callbacks, and
use them to replace the anonymous function pointers inside the
structure. This not only allows us to properly document the function
pointers, but it also allows us to annotate the arguments and return
value of those function pointers.

See also: https://gitlab.gnome.org/GNOME/gobject-introspection/-/merge_requests/400#note_1721707
2023-05-30 14:38:16 +01:00
Arnaud Rebillout
f722f11e57 Rename GTK+ to GTK (mostly comments and documentation)
GTK lost it's '+' suffix back in 2019, according to
<https://mail.gnome.org/archives/gtk-devel-list/2019-February/msg00000.html>

This commit can be re-generated with:

    git grep -l GTK+ \
    | grep -v -e ^NEWS -e ^glib/tests/collate.c \
    | xargs sed -i 's/GTK+/GTK/g'

Most of the changes are in comments and documentation.
2023-05-10 10:56:44 +07:00
Xavier Claessens
8d27474631 doc: Workaround missing API index 2023-04-14 17:08:35 +01:00
Philip Withnall
e993e27782 docs: Add 2.78 release series documentation pages to the build
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
2023-04-14 16:09:34 +01:00
Philip Withnall
783f1b8640 gtype: Improve documentation for G_TYPE_IS_CLASSED and interfaces
The documentation previously implicitly said in a few places that
interfaces are classed, but reading through the implementation of
`GType`, I don’t think they are. If they were, the registration of the
fundamental `G_TYPE_INTERFACE` in `gobject_init()` would specify
`G_TYPE_FLAG_CLASSED`. It only specifies `G_TYPE_FLAG_DERIVABLE`.

I think this makes sense, because you can’t subclass an interface.
Subclassing is a key property of being classed.

Tweak the `GType` tutorial to remove that implicit statement, and expand
the documentation for `G_TYPE_IS_CLASSED`.

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

Fixes: #252
2023-04-13 15:37:00 +01:00
Philip Withnall
ddae990509 docs: Remove a stray > in the glib-mkenums man page
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
2022-12-07 08:17:17 +00:00
Matthias Clasen
fd0dd9e93c gobject: Add G_TYPE_FLAG_DEPRECATED
This can be used to mark entire types as deprecated,
and trigger a warning when they are instantiated
and `G_ENABLE_DIAGNOSTIC=1` is set in the environment.

There's currently no convenient macros for defining
types with the new flag, but you can do:

```c
_G_DEFINE_TYPE_EXTENDED_BEGIN (GtkAppChooserWidget,
                               gtk_app_chooser_widget,
                               GTK_TYPE_WIDGET,
                               G_TYPE_FLAG_DEPRECATED)
...
_G_DEFINE_TYPE_EXTENDED_END ()
```

Includes a unit test by Philip Withnall.
2022-11-09 12:07:31 +00:00
Marco Trevisan (Treviño)
60c935a9c4 gboxed: Add GBookmarkFile as Boxed types
Now that we've a copy function we can define it as a boxed type, making
it fully introspectable.
2022-10-14 16:40:56 +01:00
Philip Withnall
05714bf635 docs: Add 2.76 release series documentation pages to the build
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
2022-10-14 16:03:29 +01:00
Xavier Claessens
dcfc9f689e Fix symbol visibility macros on Windows
There is currently no `dllimport` attribute on any of our function,
which prevents MSVC to optimize function calls.

To fix that issue, we need to redeclare all our visibility macros for
each of our libraries, because when compiling e.g. GIO code, we need
dllimport in GLIB headers and dllexport in GIO headers. That means they
cannot use the same GLIB_AVAILABLE_* macro.

Since that's a lot of boilerplate to copy/paste after each version bump,
this MR generate all those macros using a python script.

Also simplify the meson side by using `gnu_symbol_visibility : 'hidden'`
keyword argument instead of passing the cflag manually.

This leaves only API index to add manually into glib-docs.xml when
bumping GLib version. That file cannot be generated because Meson does
not allow passing a buit file to gnome.gtkdoc()'s main_xml kwarg
unfortunately.
2022-10-13 20:53:56 -04:00
Emmanuele Bassi
fa05ebe27c docs: Mention alternatives for defining enumeration types
We should mention glib-mkenums in the documentation for
G_DEFINE_ENUM_TYPE and G_DEFINE_FLAGS_TYPE.

We should also mention the macros in the documentation for glib-mkenums.

This way, developers can choose the most appropriate tool for their use
case.
2022-06-30 01:46:54 +01:00
Emmanuele Bassi
28edd84e77 docs: Add the new G_DEFINE macros for enumeration types 2022-06-30 01:46:54 +01:00
Matthias Clasen
dacfe8c88a param: Add g_param_value_is_valid
This is wrapper for the new value_is_valid vfunc,
but it falls back to using value_validate to
obtain the same information.
2022-05-23 15:48:28 -04:00
Matthias Clasen
aaef7f30b3 value: Add G_VALUE_COLLECT_INIT2
Add a variant of the G_VALUE_COLLECT_INIT() macro
that provides the GTypeValueTable to the caller.
2022-05-23 05:57:36 -04:00
Philip Withnall
8f9c5090db docs: Use G_PARAM_STATIC_STRINGS in examples and explain it more
Make it a bit clearer in the documentation that using
`G_PARAM_STATIC_STRINGS` everywhere is a good thing.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
2022-05-20 12:57:36 +01:00
Jason Francis
2a842b1173 gobject: Add g_signal_group_connect_closure 2022-04-05 15:32:20 +01:00
Philip Withnall
4f79f0712c gversionmacros: Add version macros for GLib 2.74
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
2022-03-28 12:55:20 +01:00
Christian Hergert
dd43471f60 gobject: add GSignalGroup
Much like GBindingGroup, the GSignalGroup object allows you to connect many
signal connections for an object and connect/disconnect/block/unblock them
as a group.

This is useful when using many connections on an object to ensure that they
are properly removed when changing state or disposing a third-party
object.

This has been used for years in various GNOME projects and makes sense to
have upstream instead of multiple copies.
2022-02-01 17:09:14 -08:00
Christian Hergert
0d9de09192 gobject: add GBindingGroup
Originally, GBindingGroup started with Builder as a way to simplify all
of the third-degree object bindings necessary around Model-Controller
objects such as TextBuffer/TextView.

Over time, it has grown to be useful in a number of scenarios outside
of Builder and has been copied into a number of projects such as GNOME
Text Editor, GtkSourceView, libdazzle, and more.

It makes sense at this point to unify on a single implementation and
include that upstream in GObject directly alongside GBinding.
2022-01-28 16:01:22 -08:00
Alexander Schwinn
28d833a075 Make clear in doc that signals are emitted synchroniously 2022-01-18 08:53:20 +00:00
Philip Withnall
94b74c761d gversionmacros: Add version macros for GLib 2.72
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
2021-09-17 11:35:21 +01:00
Emmanuele Bassi
ef15a4e720 docs: Add new symbols 2021-07-27 12:27:53 +01:00