diff --git a/common/flatpak-transaction.c b/common/flatpak-transaction.c
index b391ca82..5ba6ba2a 100644
--- a/common/flatpak-transaction.c
+++ b/common/flatpak-transaction.c
@@ -752,7 +752,7 @@ flatpak_transaction_class_init (FlatpakTransactionClass *klass)
   /**
    * FlatpakTransaction::add-new-remote:
    * @object: A #FlatpakTransaction
-   * @reason: The reason for the new remote is needed
+   * @reason: A #FlatpakTransactionRemoteReason for this suggestion
    * @from_id: The id of the app/runtime
    * @suggested_remote_name: The suggested remote name
    * @url: The repo url
diff --git a/common/flatpak-transaction.h b/common/flatpak-transaction.h
index 532e823c..68e7a1e9 100644
--- a/common/flatpak-transaction.h
+++ b/common/flatpak-transaction.h
@@ -40,7 +40,7 @@
  * @FLATPAK_TRANSACTION_OPERATION_UNINSTALL: Uninstall a ref
  * @FLATPAK_TRANSACTION_OPERATION_LAST_TYPE: The (currently) last operation type
  *
- * The type of a transaction, used in FlatpakTransaction::new-operation
+ * The type of a #FlatpakTransactionOperation.
  */
 typedef enum {
   FLATPAK_TRANSACTION_OPERATION_INSTALL,
@@ -54,7 +54,7 @@ typedef enum {
  * FlatpakTransactionErrorDetails
  * @FLATPAK_TRANSACTION_ERROR_DETAILS_NON_FATAL: The operation failure was not fatal
  *
- * The details for FlatpakTransaction::operation-error
+ * The details for #FlatpakTransaction::operation-error.
  */
 typedef enum {
   FLATPAK_TRANSACTION_ERROR_DETAILS_NON_FATAL = 1 << 0,
@@ -63,6 +63,8 @@ typedef enum {
 /**
  * FlatpakTransactionResult
  * @FLATPAK_TRANSACTION_RESULT_NO_CHANGE: The update caused no changes
+ *
+ * The details for #FlatpakTransaction::operation-done.
  */
 typedef enum {
   FLATPAK_TRANSACTION_RESULT_NO_CHANGE = 1 << 0,
@@ -72,6 +74,8 @@ typedef enum {
  * FlatpakTransactionRemoteReason
  * @FLATPAK_TRANSACTION_REMOTE_GENERIC_REPO: The remote specified in the flatpakref has other apps too
  * @FLATPAK_TRANSACTION_REMOTE_RUNTIME_DEPS: The remote has runtimes needed for the app
+ *
+ * The reason for #FlatpakTransaction::add-new-remote.
  */
 typedef enum {
   FLATPAK_TRANSACTION_REMOTE_GENERIC_REPO,
diff --git a/doc/reference/flatpak-sections.txt b/doc/reference/flatpak-sections.txt
index 7d3e94c3..58293eff 100644
--- a/doc/reference/flatpak-sections.txt
+++ b/doc/reference/flatpak-sections.txt
@@ -220,6 +220,7 @@ flatpak_transaction_operation_get_type
 FlatpakTransaction
 FlatpakTransactionOperationType
 FlatpakTransactionErrorDetails
+FlatpakTransactionRemoteReason
 FlatpakTransactionResult
 flatpak_transaction_new_for_installation
 flatpak_transaction_add_install