doc: Fix gtk-doc warnings and missing symbols

Fix XML parse error caused by unescaped <path> in
flatpak_transaction_add_sideload_image_collection doc comment.
Add missing public API symbols to flatpak-sections.txt and remove
private flatpak_related_ref_new. Add ignore lists for private headers
and source files to prevent gtkdoc-mkdb from scanning them.

common/flatpak-transaction.c

@@ -566,13 +566,15 @@ flatpak_transaction_add_sideload_repo (FlatpakTransaction  *self,
  * flatpak_transaction_add_sideload_image_collection:
  * @self: a #FlatpakTransaction
  * @location: source of images for installation
+ * @cancellable: (nullable): a #GCancellable
+ * @error: return location for a #GError
  *
  * Adds a set of images to be used as source for installation. This is similar
  * to flatpak_transaction_add_sideload_repo(), but the Flatpaks are stored
  * as OCI images rather than ostree commits, and the images are used for
  * all OCI remotes without regard to collection ID.
  *
- * Currently @location should be either 'oci:<path>' or 'oci-archive:<path>'.
+ * Currently @location should be either `oci:&lt;path&gt;` or `oci-archive:&lt;path&gt;`.
  * Additional schemes may be added in the future.
  *
  * Since: 1.7.1
@@ -2931,7 +2933,7 @@ flatpak_transaction_add_install (FlatpakTransaction *self,
  * See flatpak_transaction_add_install() for a description of @remote.
  *
  * Returns: %TRUE on success; %FALSE with @error set on failure.
- * Since: 1.3.3.
+ * Since: 1.3.3
  */
 gboolean
 flatpak_transaction_add_rebase (FlatpakTransaction *self,

doc/reference/flatpak-sections.txt

@@ -39,10 +39,13 @@ flatpak_installation_list_installed_refs_by_kind
 flatpak_installation_list_installed_refs_for_update
 flatpak_installation_list_installed_related_refs_sync
 flatpak_installation_list_unused_refs
+flatpak_installation_list_unused_refs_with_options
+flatpak_installation_list_pinned_refs
 flatpak_installation_list_remote_refs_sync
 flatpak_installation_list_remote_refs_sync_full
 flatpak_installation_list_remotes_by_type
 flatpak_installation_list_remote_related_refs_sync
+flatpak_installation_list_remote_related_refs_for_installed_sync
 flatpak_installation_list_remotes
 flatpak_installation_get_remote_by_name
 flatpak_installation_fetch_remote_metadata_sync
@@ -134,7 +137,6 @@ flatpak_remote_ref_get_type
 <FILE>flatpak-related-ref</FILE>
 <TITLE>FlatpakRelatedRef</TITLE>
 FlatpakRelatedRef
-flatpak_related_ref_new
 flatpak_related_ref_get_subpaths
 flatpak_related_ref_should_download
 flatpak_related_ref_should_delete
@@ -153,6 +155,7 @@ flatpak_related_ref_get_type
 FlatpakRef
 FlatpakRefKind
 flatpak_ref_format_ref
+flatpak_ref_format_ref_cached
 flatpak_ref_get_arch
 flatpak_ref_get_branch
 flatpak_ref_get_collection_id
@@ -243,15 +246,19 @@ flatpak_transaction_progress_get_type
 <FILE>flatpak-transaction-operation</FILE>
 <TITLE>FlatpakTransactionOperation</TITLE>
 FlatpakTransactionOperation
-flatpak_transaction_operation_get_bundle_path
-flatpak_transaction_operation_get_commit
 flatpak_transaction_operation_get_operation_type
 flatpak_transaction_operation_get_ref
+flatpak_transaction_operation_get_related_to_ops
+flatpak_transaction_operation_get_is_skipped
 flatpak_transaction_operation_get_remote
-flatpak_transaction_operation_get_metadata
-flatpak_transaction_operation_get_old_metadata
+flatpak_transaction_operation_get_bundle_path
+flatpak_transaction_operation_get_commit
 flatpak_transaction_operation_get_download_size
 flatpak_transaction_operation_get_installed_size
+flatpak_transaction_operation_get_metadata
+flatpak_transaction_operation_get_old_metadata
+flatpak_transaction_operation_get_subpaths
+flatpak_transaction_operation_get_requires_authentication
 flatpak_transaction_operation_type_to_string
 <SUBSECTION Standard>
 FlatpakTransactionOperationClass
@@ -272,35 +279,50 @@ FlatpakTransactionResult
 flatpak_transaction_new_for_installation
 flatpak_transaction_add_install
 flatpak_transaction_add_install_bundle
+flatpak_transaction_add_install_image
 flatpak_transaction_add_install_flatpakref
 flatpak_transaction_add_rebase
 flatpak_transaction_add_rebase_and_uninstall
+flatpak_transaction_add_sync_preinstalled
 flatpak_transaction_add_update
 flatpak_transaction_add_uninstall
 flatpak_transaction_add_default_dependency_sources
 flatpak_transaction_add_dependency_source
+flatpak_transaction_add_sideload_repo
+flatpak_transaction_add_sideload_image_collection
 flatpak_transaction_run
 <SUBSECTION>
 flatpak_transaction_get_current_operation
+flatpak_transaction_get_operation_for_ref
 flatpak_transaction_get_installation
 flatpak_transaction_get_operations
 flatpak_transaction_is_empty
 <SUBSECTION>
-flatpak_transaction_set_disable_dependencies
-flatpak_transaction_set_disable_prune
-flatpak_transaction_set_disable_related
-flatpak_transaction_set_disable_static_deltas
-flatpak_transaction_set_no_deploy
-flatpak_transaction_get_no_deploy
 flatpak_transaction_set_no_pull
 flatpak_transaction_get_no_pull
+flatpak_transaction_set_no_deploy
+flatpak_transaction_get_no_deploy
+flatpak_transaction_set_disable_static_deltas
+flatpak_transaction_set_disable_prune
+flatpak_transaction_set_disable_dependencies
+flatpak_transaction_set_disable_related
+flatpak_transaction_set_disable_auto_pin
 flatpak_transaction_set_reinstall
+flatpak_transaction_get_no_interaction
+flatpak_transaction_set_no_interaction
 flatpak_transaction_set_force_uninstall
 flatpak_transaction_set_default_arch
-<subsection>
+flatpak_transaction_set_include_unused_uninstall_ops
+flatpak_transaction_get_include_unused_uninstall_ops
+flatpak_transaction_set_auto_install_sdk
+flatpak_transaction_get_auto_install_sdk
+flatpak_transaction_set_auto_install_debug
+flatpak_transaction_get_auto_install_debug
+<SUBSECTION>
 flatpak_transaction_set_parent_window
 flatpak_transaction_get_parent_window
 flatpak_transaction_abort_webflow
+flatpak_transaction_complete_basic_auth
 
 <SUBSECTION Standard>
 FlatpakTransactionClass

doc/reference/meson.build

@@ -36,46 +36,119 @@ libflatpak_doc = gnome.gtkdoc(
   content_files : doc_gdbus[2],
   dependencies : base_deps + [libflatpak_dep],
   ignore_headers : [
-    'valgrind-private.h',
+    'flatpak-appdata-private.h',
+    'flatpak-auth-private.h',
     'flatpak-bwrap-private.h',
     'flatpak-chain-input-stream-private.h',
     'flatpak-common-types-private.h',
     'flatpak-context-private.h',
     'flatpak-dbus-generated.h',
     'flatpak-dir-private.h',
+    'flatpak-dir-utils-private.h',
+    'flatpak-docker-reference-private.h',
     'flatpak-document-dbus-generated.h',
     'flatpak-enum-types.h',
     'flatpak-exports-private.h',
+    'flatpak-glib-backports-private.h',
     'flatpak-image-collection-private.h',
     'flatpak-image-source-private.h',
+    'flatpak-installation-private.h',
     'flatpak-installed-ref-private.h',
-    'flatpak-permission-dbus-generated.h',
+    'flatpak-instance-private.h',
+    'flatpak-json-backports-private.h',
     'flatpak-json-oci-private.h',
     'flatpak-json-private.h',
+    'flatpak-locale-utils-private.h',
+    'flatpak-metadata-private.h',
     'flatpak-oci-registry-private.h',
+    'flatpak-oci-signatures-private.h',
+    'flatpak-parental-controls-private.h',
+    'flatpak-permission-dbus-generated.h',
+    'flatpak-permission-utils-private.h',
     'flatpak-progress-private.h',
+    'flatpak-prune-private.h',
+    'flatpak-ref-utils-private.h',
+    'flatpak-related-ref-private.h',
     'flatpak-remote-private.h',
     'flatpak-remote-ref-private.h',
+    'flatpak-repo-utils-private.h',
+    'flatpak-run-cups-private.h',
+    'flatpak-run-dbus-private.h',
     'flatpak-run-private.h',
+    'flatpak-run-pulseaudio-private.h',
+    'flatpak-run-sockets-private.h',
+    'flatpak-run-wayland-private.h',
+    'flatpak-run-x11-private.h',
+    'flatpak-syscalls-private.h',
     'flatpak-systemd-dbus-generated.h',
-    'flatpak-installation-private.h',
     'flatpak-transaction-private.h',
-    'flatpak-utils-private.h',
+    'flatpak-uri-private.h',
+    'flatpak-usb-private.h',
     'flatpak-utils-base-private.h',
     'flatpak-utils-http-private.h',
-    'flatpak-instance-private.h',
-    'flatpak-auth-private.h',
-    'flatpak-parental-controls-private.h',
-    'flatpak-permission-utils-private.h',
-    'flatpak-appdata-private.h',
+    'flatpak-utils-private.h',
+    'flatpak-variant-impl-private.h',
+    'flatpak-variant-private.h',
+    'flatpak-xml-utils-private.h',
     'flatpak-zstd-compressor-private.h',
     'flatpak-zstd-decompressor-private.h',
+    'security-context-v1-protocol.h',
+    'valgrind-private.h',
   ],
   install : true,
   scan_args : [
     '--ignore-decorators=FLATPAK_EXTERN',
     '--rebuild-types',
   ],
+  mkdb_args : [
+    '--ignore-files=' + ' '.join([
+      'flatpak.c',
+      'flatpak-appdata.c',
+      'flatpak-auth.c',
+      'flatpak-bwrap.c',
+      'flatpak-chain-input-stream.c',
+      'flatpak-context.c',
+      'flatpak-dbus-generated.c',
+      'flatpak-dir.c',
+      'flatpak-dir-utils.c',
+      'flatpak-docker-reference.c',
+      'flatpak-document-dbus-generated.c',
+      'flatpak-exports.c',
+      'flatpak-glib-backports.c',
+      'flatpak-image-collection.c',
+      'flatpak-image-source.c',
+      'flatpak-json.c',
+      'flatpak-json-oci.c',
+      'flatpak-locale-utils.c',
+      'flatpak-oci-registry.c',
+      'flatpak-oci-signatures.c',
+      'flatpak-parental-controls.c',
+      'flatpak-permission-dbus-generated.c',
+      'flatpak-permission-utils.c',
+      'flatpak-progress.c',
+      'flatpak-prune.c',
+      'flatpak-ref-utils.c',
+      'flatpak-repo-utils.c',
+      'flatpak-run.c',
+      'flatpak-run-cups.c',
+      'flatpak-run-dbus.c',
+      'flatpak-run-pulseaudio.c',
+      'flatpak-run-sockets.c',
+      'flatpak-run-wayland.c',
+      'flatpak-run-x11.c',
+      'flatpak-systemd-dbus-generated.c',
+      'flatpak-uri.c',
+      'flatpak-usb.c',
+      'flatpak-utils.c',
+      'flatpak-utils-base.c',
+      'flatpak-utils-http.c',
+      'flatpak-xml-utils.c',
+      'flatpak-zstd-compressor.c',
+      'flatpak-zstd-decompressor.c',
+      'security-context-v1-protocol.h',
+      'test-lib.c',
+    ]),
+  ],
 )
 
 if xmlto.found()
@@ -99,4 +172,4 @@ if xmlto.found()
     install : true,
     install_dir : docdir,
   )
-endif
+endif