docs: fix gtk-doc warnings and update version infos

Move things around and rename things until gtk-doc is happy.

This also moves the "Since" annotations to the next stable releases and
adds version added info for g_callable_info_get_instance_ownership_transfer()
and g_struct_info_find_field().

22 files changed, 55 insertions, 48 deletions

diff --git a/girepository/giarginfo.c b/girepository/giarginfo.c
index 6bc53c48..381c3839 100644
--- a/girepository/giarginfo.c
+++ b/girepository/giarginfo.c
@@ -41,7 +41,7 @@
  * <refsect1 id="gi-giarginfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----GIArgInfo
  * </synopsis>
  * </refsect1>
@@ -179,7 +179,7 @@ g_arg_info_may_be_null (GIArgInfo *info)
  * Obtain if an argument is only useful in C.
  *
  * Returns: %TRUE if argument is only useful in C.
- * Since: 1.29.0
+ * Since: 1.30
  */
 gboolean
 g_arg_info_is_skip (GIArgInfo *info)
diff --git a/girepository/gibaseinfo.h b/girepository/gibaseinfo.h
index 52471df3..f8f7191b 100644
--- a/girepository/gibaseinfo.h
+++ b/girepository/gibaseinfo.h
@@ -34,23 +34,6 @@
 G_BEGIN_DECLS
 
 /**
- * GIBaseInfoStub:
- *
- * TODO
- */
-struct _GIBaseInfoStub {
-  /* <private> */
-  gint32 dummy1;
-  gint32 dummy2;
-  gpointer dummy3;
-  gpointer dummy4;
-  gpointer dummy5;
-  guint32  dummy6;
-  guint32  dummy7;
-  gpointer padding[4];
-};
-
-/**
  * GIAttributeIter:
  *
  * An opaque structure used to iterate over attributes
diff --git a/girepository/gicallableinfo.c b/girepository/gicallableinfo.c
index e9a426e1..3048e162 100644
--- a/girepository/gicallableinfo.c
+++ b/girepository/gicallableinfo.c
@@ -48,7 +48,7 @@
  * <refsect1 id="gi-gicallableinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----GICallableInfo
  *          +----<link linkend="gi-GIFunctionInfo">GIFunctionInfo</link>
  *          +----<link linkend="gi-GISignalInfo">GISignalInfo</link>
@@ -297,6 +297,7 @@ g_callable_info_get_caller_owns (GICallableInfo *info)
  * Obtains the ownership transfer for the instance argument.
  * #GITransfer contains a list of possible transfer values.
  *
+ * Since: 1.42
  * Returns: the transfer mode of the instance argument
  */
 GITransfer
diff --git a/girepository/giconstantinfo.c b/girepository/giconstantinfo.c
index d44646ee..c18a9d3f 100644
--- a/girepository/giconstantinfo.c
+++ b/girepository/giconstantinfo.c
@@ -41,7 +41,7 @@
  * <refsect1 id="gi-giconstantinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----GIConstantInfo
  * </synopsis>
  * </refsect1>
@@ -78,7 +78,7 @@ g_constant_info_get_type (GIConstantInfo *info)
  *
  * Free the value returned from g_constant_info_get_value().
  *
- * Since: 1.30.1
+ * Since: 1.32
  */
 void
 g_constant_info_free_value (GIConstantInfo *info,
diff --git a/girepository/gienuminfo.c b/girepository/gienuminfo.c
index 42930b2f..2dc4b167 100644
--- a/girepository/gienuminfo.c
+++ b/girepository/gienuminfo.c
@@ -40,7 +40,7 @@
  * <refsect1 id="gi-gienuminfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
  *          +----GIEnumInfo
  * </synopsis>
@@ -78,7 +78,7 @@ g_enum_info_get_n_values (GIEnumInfo *info)
  *
  * Returns: (transfer none): the string form of the error domain associated
  * with this enum, or %NULL.
- * Since: 1.29.17
+ * Since: 1.30
  */
 const gchar *
 g_enum_info_get_error_domain (GIEnumInfo *info)
@@ -132,7 +132,7 @@ g_enum_info_get_value (GIEnumInfo *info,
  * Obtain the number of methods that this enum type has.
  *
  * Returns: number of methods
- * Since: 1.29.17
+ * Since: 1.30
  */
 gint
 g_enum_info_get_n_methods (GIEnumInfo *info)
@@ -157,7 +157,7 @@ g_enum_info_get_n_methods (GIEnumInfo *info)
  *
  * Returns: (transfer full): the #GIFunctionInfo. Free the struct by calling
  * g_base_info_unref() when done.
- * Since: 1.29.17
+ * Since: 1.30
  */
 GIFunctionInfo *
 g_enum_info_get_method (GIEnumInfo *info,
diff --git a/girepository/gifieldinfo.c b/girepository/gifieldinfo.c
index 4d07304e..b5264ec7 100644
--- a/girepository/gifieldinfo.c
+++ b/girepository/gifieldinfo.c
@@ -44,7 +44,7 @@
  * <refsect1 id="gi-gifieldinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----GIFieldInfo
  * </synopsis>
  * </refsect1>
diff --git a/girepository/gifunctioninfo.c b/girepository/gifunctioninfo.c
index b5720244..366850d5 100644
--- a/girepository/gifunctioninfo.c
+++ b/girepository/gifunctioninfo.c
@@ -45,7 +45,7 @@
  * <refsect1 id="gi-gifunctioninfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----<link linkend="gi-GICallableInfo">GICallableInfo</link>
  *          +----GIFunctionInfo
  *          +----<link linkend="gi-GISignalInfo">GISignalInfo</link>
diff --git a/girepository/giinterfaceinfo.c b/girepository/giinterfaceinfo.c
index d60729c3..203113b6 100644
--- a/girepository/giinterfaceinfo.c
+++ b/girepository/giinterfaceinfo.c
@@ -41,7 +41,7 @@
  * <refsect1 id="gi-giinterfaceinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
  *          +----GIInterfaceInfo
  * </synopsis>
diff --git a/girepository/giobjectinfo.c b/girepository/giobjectinfo.c
index 0991b80e..fb57bd62 100644
--- a/girepository/giobjectinfo.c
+++ b/girepository/giobjectinfo.c
@@ -42,7 +42,7 @@
  * <refsect1 id="gi-giobjectinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
  *          +----GIObjectInfo
  * </synopsis>
diff --git a/girepository/gipropertyinfo.c b/girepository/gipropertyinfo.c
index 338f360b..e58d4600 100644
--- a/girepository/gipropertyinfo.c
+++ b/girepository/gipropertyinfo.c
@@ -39,7 +39,7 @@
  * <refsect1 id="gi-gipropertyinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----GIPropertyInfo
  * </synopsis>
  * </refsect1>
diff --git a/girepository/giregisteredtypeinfo.c b/girepository/giregisteredtypeinfo.c
index 1555c459..411b9b95 100644
--- a/girepository/giregisteredtypeinfo.c
+++ b/girepository/giregisteredtypeinfo.c
@@ -47,7 +47,7 @@
  * <refsect1 id="gi-giregisteredtypeinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----GIRegisteredTypeInfo
  *          +----<link linkend="gi-GIEnumInfo">GIEnumInfo</link>
  *          +----<link linkend="gi-GIInterfaceInfo">GIInterfaceInfo</link>
diff --git a/girepository/girepository.c b/girepository/girepository.c
index c1fa3d3a..8bc49eb1 100644
--- a/girepository/girepository.c
+++ b/girepository/girepository.c
@@ -220,7 +220,7 @@ g_irepository_prepend_search_path (const char *directory)
  * g_irepository_get_search_path:
  *
  * Returns the current search path #GIRepository will use when loading
- * typelib files. The list is internal to #GIRespository and should not
+ * typelib files. The list is internal to #GIRepository and should not
  * be freed, nor should its string elements.
  *
  * Returns: (element-type filename) (transfer none): #GSList of strings
@@ -900,7 +900,7 @@ find_by_error_domain_foreach (gpointer key,
  *
  * Returns: (transfer full): #GIEnumInfo representing metadata about @domain's
  * enum type, or %NULL
- * Since: 1.29.17
+ * Since: 1.30
  */
 GIEnumInfo *
 g_irepository_find_by_error_domain (GIRepository *repository,
diff --git a/girepository/gisignalinfo.c b/girepository/gisignalinfo.c
index e72890d7..5f8fa880 100644
--- a/girepository/gisignalinfo.c
+++ b/girepository/gisignalinfo.c
@@ -42,7 +42,7 @@
  * <refsect1 id="gi-gisignalinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----<link linkend="gi-GICallableInfo">GICallableInfo</link>
  *          +----<link linkend="gi-GIFunctionInfo">GIFunctionInfo</link>
  *          +----GISignalInfo
diff --git a/girepository/gistructinfo.c b/girepository/gistructinfo.c
index bd777463..7db417fc 100644
--- a/girepository/gistructinfo.c
+++ b/girepository/gistructinfo.c
@@ -42,7 +42,7 @@
  * <refsect1 id="gi-giobjectinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
  *          +----GIStructInfo
  * </synopsis>
@@ -123,6 +123,7 @@ g_struct_info_get_field (GIStructInfo *info,
  *
  * Obtain the type information for field named @name.
  *
+ * Since: 1.46
  * Returns: (transfer full): the #GIFieldInfo or %NULL if not found,
  * free it with g_base_info_unref() when done.
  */
diff --git a/girepository/gistructinfo.h b/girepository/gistructinfo.h
index 4a60d5bb..6e70fea7 100644
--- a/girepository/gistructinfo.h
+++ b/girepository/gistructinfo.h
@@ -48,7 +48,7 @@ GI_AVAILABLE_IN_ALL
 GIFieldInfo *    g_struct_info_get_field       (GIStructInfo *info,
 						gint          n);
 
-GI_AVAILABLE_IN_ALL
+GI_AVAILABLE_IN_1_46
 GIFieldInfo *    g_struct_info_find_field      (GIStructInfo *info,
 						const gchar  *name);
 
diff --git a/girepository/gitypeinfo.c b/girepository/gitypeinfo.c
index 8b2e3ec9..1434b2f3 100644
--- a/girepository/gitypeinfo.c
+++ b/girepository/gitypeinfo.c
@@ -46,7 +46,7 @@
  * <refsect1 id="gi-gitypeinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----GITypeInfo
  * </synopsis>
  * </refsect1>
diff --git a/girepository/gitypelib-internal.h b/girepository/gitypelib-internal.h
index 281192eb..b44ba041 100644
--- a/girepository/gitypelib-internal.h
+++ b/girepository/gitypelib-internal.h
@@ -528,7 +528,7 @@ typedef struct {
  * @constructor: The function acts as a constructor for the object it is
  *   contained in.
  * @wraps_vfunc: The function is a simple wrapper for a virtual function.
- * @throws: (deprecated): This is now additionally stored in the #SignatureBlob.
+ * @throws: This is now additionally stored in the #SignatureBlob. (deprecated)
  * @index: Index of the property that this function is a setter or getter of
  *   in the array of properties of the containing interface, or index
  *   of the virtual function that this function wraps.
@@ -996,7 +996,7 @@ typedef struct {
  *   virtual function.
  * @class_closure: Set if this virtual function is the class closure of a
  *   signal.
- * @throws: (deprecated): This is now additionally stored in the #SignatureBlob.
+ * @throws: This is now additionally stored in the #SignatureBlob. (deprecated)
  * @reserved: Reserved for future use.
  * @signal: The index of the signal in the list of signals of the object or
  *   interface to which this virtual function belongs.
diff --git a/girepository/gitypelib.c b/girepository/gitypelib.c
index dbc7261e..de11748b 100644
--- a/girepository/gitypelib.c
+++ b/girepository/gitypelib.c
@@ -2235,7 +2235,7 @@ static GSList *library_paths;
  * path (ie. LD_LIBRARY_PATH and DT_RPATH in ELF systems).
  * See the documentation of your dynamic linker for full details.
  *
- * Since: 1.35.8
+ * Since: 1.36
  */
 void
 g_irepository_prepend_library_path (const char *directory)
diff --git a/girepository/gitypes.h b/girepository/gitypes.h
index b96ae0b3..33897520 100644
--- a/girepository/gitypes.h
+++ b/girepository/gitypes.h
@@ -31,9 +31,17 @@
 
 G_BEGIN_DECLS
 
-#ifndef __GTK_DOC_IGNORE__
-typedef struct _GIBaseInfoStub GIBaseInfo;
-#endif
+typedef struct _GIBaseInfoStub {
+  /* <private> */
+  gint32 dummy1;
+  gint32 dummy2;
+  gpointer dummy3;
+  gpointer dummy4;
+  gpointer dummy5;
+  guint32  dummy6;
+  guint32  dummy7;
+  gpointer padding[4];
+} GIBaseInfo;
 
 /**
  * GICallableInfo:
@@ -60,7 +68,7 @@ typedef GIBaseInfo GIFunctionInfo;
  * <refsect1 id="gi-gicallbackinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----<link linkend="gi-GICallableInfo">GICallableInfo</link>
  *          +----GIFunctionInfo
  *          +----<link linkend="gi-GISignalInfo">GISignalInfo</link>
@@ -135,7 +143,7 @@ typedef GIBaseInfo GIConstantInfo;
  * <refsect1 id="gi-givalueinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----GIValueInfo
  * </synopsis>
  * </refsect1>
diff --git a/girepository/giunioninfo.c b/girepository/giunioninfo.c
index 9a7f8613..7bc81aa0 100644
--- a/girepository/giunioninfo.c
+++ b/girepository/giunioninfo.c
@@ -42,7 +42,7 @@
  * <refsect1 id="gi-giobjectinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
  *          +----GIUnionInfo
  * </synopsis>
diff --git a/girepository/giversionmacros.h b/girepository/giversionmacros.h
index 3c2faf47..bf8a0861 100644
--- a/girepository/giversionmacros.h
+++ b/girepository/giversionmacros.h
@@ -139,4 +139,18 @@
 # define GI_AVAILABLE_IN_1_44                 _GI_EXTERN
 #endif
 
+#if GLIB_VERSION_MIN_REQUIRED >= GLIB_VERSION_2_46
+# define GI_DEPRECATED_IN_1_46                GLIB_DEPRECATED
+# define GI_DEPRECATED_IN_1_46_FOR(f)         GLIB_DEPRECATED_FOR(f)
+#else
+# define GI_DEPRECATED_IN_1_46                _GI_EXTERN
+# define GI_DEPRECATED_IN_1_46_FOR(f)         _GI_EXTERN
+#endif
+
+#if GLIB_VERSION_MAX_ALLOWED < GLIB_VERSION_2_46
+# define GI_AVAILABLE_IN_1_46                 GLIB_UNAVAILABLE(2, 46)
+#else
+# define GI_AVAILABLE_IN_1_46                 _GI_EXTERN
+#endif
+
 #endif /* __GIVERSIONMACROS_H__ */
diff --git a/girepository/givfuncinfo.c b/girepository/givfuncinfo.c
index f20bfb06..13ab654d 100644
--- a/girepository/givfuncinfo.c
+++ b/girepository/givfuncinfo.c
@@ -41,7 +41,7 @@
  * <refsect1 id="gi-givfuncinfo.struct-hierarchy" role="struct_hierarchy">
  * <title role="struct_hierarchy.title">Struct hierarchy</title>
  * <synopsis>
- *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *   <link linkend="GIBaseInfo">GIBaseInfo</link>
  *    +----<link linkend="gi-GICallableInfo">GICallableInfo</link>
  *          +----<link linkend="gi-GIFunctionInfo">GIFunctionInfo</link>
  *          +----<link linkend="gi-GISignalInfo">GISignalInfo</link>