docs: Add migration guide for libgirepository

This covers all the API changes from girepository-1.0 to
girepository-2.0 so far.

It was generated by manually looking through the changes in `git diff
af36393e6.. -- girepository/*.h`.

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

Helps: #3155

docs/reference/girepository/girepository.toml.in

@@ -45,6 +45,7 @@ show_class_hierarchy = true
 urlmap_file = "urlmap.js"
 # The same order will be used when generating the index
 content_files = [
+  "migrating-gi.md",
 ]
 content_images = [
 ]

docs/reference/girepository/meson.build

@@ -1,4 +1,8 @@
 if get_option('documentation') and enable_gir
+  expand_content_files = [
+    'migrating-gi.md',
+  ]
+
   girepository_toml = configure_file(
     input: 'girepository.toml.in',
     output: 'girepository.toml',
@@ -21,5 +25,6 @@ if get_option('documentation') and enable_gir
       '@INPUT1@',
     ],
     build_by_default: true,
+    depend_files: expand_content_files,
   )
 endif

docs/reference/girepository/migrating-gi.md

@@ -0,0 +1,76 @@
+Title: Migrating from girepository-1.0 to girepository-2.0
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2014 GNOME Foundation
+
+# Migrating from girepository-1.0 to girepository-2.0
+
+libgirepository was originally part of
+[gobject-introspection](https://gitlab.gnome.org/GNOME/gobject-introspection/),
+where it was prototyped for a number of years.
+
+Now that it’s considered stable (for a long time), it’s been moved to
+[glib](https://gitlab.gnome.org/GNOME/glib/) in order to simplify the build
+process of the two modules.
+
+As part of this move, the API version has been bumped from 1.0 to 2.0, and some
+fairly straightforward API changes have been made. Note that the GIR version
+was previously 2.0, and is now 3.0 — so the new version of libgirepository uses
+`girepository-2.0.pc` and `GIRepository-3.0.typelib`.
+
+The main change between the two versions of libgirepository is that it now uses
+[type@GObject.TypeInstance] as the basis of its type system, rather than simple
+C struct aliasing. This means that [type@GIRepository.BaseInfo] instances are
+now reference counted using [method@GIRepository.BaseInfo.ref] and
+[method@GIRepository.BaseInfo.unref].
+
+It also means that runtime cast macros such as [func@GIRepository.CALLABLE_INFO]
+are now available. Using these instead of simple C casts can improve the runtime
+type safety of your code.
+
+Stack allocation of some [type@GIRepository.BaseInfo] subtypes is still
+possible, but they must now be cleared using
+[method@GIRepository.BaseInfo.clear] once finished with. Previously this wasn’t
+necessary.
+
+As part of moving the code over, the symbol prefix has changed from `g_` to
+`gi_` — this has affected every API in the library, but trivially.
+
+The types of various function arguments have changed — for example from
+`guint32` to `size_t` for most offsets. This will require minor adjustments in
+your code if integer type warnings are enabled.
+
+## API replacements from version 1.0 to 2.0
+
+| girepository-1.0 | girepository-2.0 |
+|------------------|------------------|
+| `GI_CHECK_VERSION` | [func@GLib.CHECK_VERSION] |
+| `g_arg_info_get_closure` | [method@GIRepository.ArgInfo.get_closure_index] |
+| `g_arg_info_get_destroy` | [method@GIRepository.ArgInfo.get_destroy_index] |
+| `g_arg_info_get_type` | [method@GIRepository.ArgInfo.get_type_info] |
+| `g_arg_info_load_type` | [method@GIRepository.ArgInfo.load_type_info] |
+| - | [method@GIRepository.BaseInfo.ref] and [method@GIRepository.BaseInfo.unref] |
+| `g_base_info_get_type` | [method@GIRepository.BaseInfo.get_info_type] |
+| `g_callable_info_invoke` arguments | `is_method` and `throws` dropped in [method@GIRepository.CallableInfo.invoke] |
+| `g_constant_info_get_type` | [method@GIRepository.ConstantInfo.get_type_info] |
+| `g_field_info_get_type` | [method@GIRepository.FieldInfo.get_type_info] |
+| `g_object_info_get_type_init` | [method@GIRepository.ObjectInfo.get_type_init_function_name] |
+| `g_object_info_get_ref_function` | [method@GIRepository.ObjectInfo.get_ref_function_name] |
+| `g_object_info_get_unref_function` | [method@GIRepository.ObjectInfo.get_unref_function_name] |
+| `g_object_info_get_set_value_function` | [method@GIRepository.ObjectInfo.get_set_value_function_name] |
+| `g_object_info_get_get_value_function` | [method@GIRepository.ObjectInfo.get_get_value_function_name] |
+| `g_property_info_get_type` | [method@GIRepository.PropertyInfo.get_type_info] |
+| `g_registered_type_info_get_type_init` | [method@GIRepository.RegisteredTypeInfo.get_type_init_function_name] |
+| `g_irepository_*` | `gi_repository_*` |
+| `g_irepository_get_default` | Singleton object removed; create separate [class@GIRepository.Repository] instances instead |
+| `g_irepository_get_search_path` and `g_irepository_get_library_path` | Now return arrays rather than linked lists |
+| `g_irepository_enumerate_versions` | Now returns an array rather than a linked list |
+| `g_irepository_dump` | Takes structured `input_filename` and `output_filename` arguments rather than a single formatted string |
+| `g_function_invoker_destroy` | `gi_function_invoker_clear()` |
+| `g_struct_info_get_copy_function` | [method@GIRepository.StructInfo.get_copy_function_name] |
+| `g_struct_info_get_free_function` | [method@GIRepository.StructInfo.get_free_function_name] |
+| `g_type_info_get_array_length` and `g_type_info_get_array_fixed_size` | Split success and failure return values out into a new out-argument and return value |
+| `g_type_info_get_array_length` | [method@GIRepository.TypeInfo.get_array_length_index] |
+| `g_typelib_new_from_*` | All replaced with `gi_typelib_new_from_bytes()` |
+| `GI_FUNCTION_THROWS` and `GI_VFUNC_THROWS` | [method@GIRepository.CallableInfo.can_throw_gerror] |
+| `g_union_info_get_copy_function` | [method@GIRepository.UnionInfo.get_copy_function_name] |
+| `g_union_info_get_free_function` | [method@GIRepository.UnionInfo.get_free_function_name] |