[CDRIVER-4402] Document Queryable Encryption as an experimental API (#1036)

vector-of-bool · kevinAlbs · commit 270725d25ca3 · 2022-06-29T11:56:36.000-04:00
diff --git a/src/libmongoc/doc/conf.py b/src/libmongoc/doc/conf.py
@@ -51,6 +51,23 @@
     'configuring_tls': [],  # Make more room for the big table.
 }
 
+rst_prolog = '''
+.. |qenc:is-experimental| replace::
+
+    is part of the experimental
+    :doc:`Queryable Encryption </queryable-encryption>` API and may be subject
+    to breaking changes in future releases.
+
+.. |qenc:opt-is-experimental| replace::
+
+    This option |qenc:is-experimental|
+
+.. |qenc:api-is-experimental| replace::
+
+    This API |qenc:is-experimental|
+
+'''
+
 
 def add_canonical_link(app, pagename, templatename, context, doctree):
     link = ('<link rel="canonical"'
diff --git a/src/libmongoc/doc/mongoc_auto_encryption_opts_set_bypass_query_analysis.rst b/src/libmongoc/doc/mongoc_auto_encryption_opts_set_bypass_query_analysis.rst
@@ -12,6 +12,8 @@ Synopsis
    mongoc_auto_encryption_opts_set_bypass_query_analysis (
       mongoc_auto_encryption_opts_t *opts, bool bypass_query_analysis);
 
+.. important:: |qenc:api-is-experimental|
+.. versionadded:: 1.22.0
 
 Parameters
 ----------
diff --git a/src/libmongoc/doc/mongoc_auto_encryption_opts_set_encrypted_fields_map.rst b/src/libmongoc/doc/mongoc_auto_encryption_opts_set_encrypted_fields_map.rst
@@ -12,6 +12,8 @@ Synopsis
    mongoc_auto_encryption_opts_set_encrypted_fields_map (
       mongoc_auto_encryption_opts_t *opts, const bson_t *encrypted_fields_map);
 
+.. important:: |qenc:api-is-experimental|
+.. versionadded:: 1.22.0
 
 Parameters
 ----------
diff --git a/src/libmongoc/doc/mongoc_client_encryption_encrypt.rst b/src/libmongoc/doc/mongoc_client_encryption_encrypt.rst
@@ -20,9 +20,15 @@ Performs explicit encryption.
 
 ``ciphertext`` is always initialized (even on failure). Caller must call :symbol:`bson_value_destroy()` to free.
 
-To insert or query with an "Indexed" encrypted payload, use a :symbol:`mongoc_client_t` configured with :symbol:`mongoc_auto_encryption_opts_t`.
-The :symbol:`mongoc_auto_encryption_opts_t` may be configured to bypass query analysis with :symbol:`mongoc_auto_encryption_opts_set_bypass_query_analysis`.
-The :symbol:`mongoc_auto_encryption_opts_t` must not be configured to bypass automatic encryption with :symbol:`mongoc_auto_encryption_opts_set_bypass_auto_encryption`.
+To insert or query with an "Indexed" encrypted payload, use a
+:symbol:`mongoc_client_t` configured with
+:symbol:`mongoc_auto_encryption_opts_t`. The
+:symbol:`mongoc_auto_encryption_opts_t` may be configured to bypass query
+analysis with :symbol:`mongoc_auto_encryption_opts_set_bypass_query_analysis`.
+The :symbol:`mongoc_auto_encryption_opts_t` must not be configured to bypass
+automatic encryption with
+:symbol:`mongoc_auto_encryption_opts_set_bypass_auto_encryption`. **Note** that
+the ``"Indexed"`` payload type |qenc:is-experimental|
 
 Parameters
 ----------
diff --git a/src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_algorithm.rst b/src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_algorithm.rst
@@ -14,15 +14,32 @@ Synopsis
 
    #define MONGOC_AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM "AEAD_AES_256_CBC_HMAC_SHA_512-Random"
    #define MONGOC_AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"
+   // (Experimental: See below)
    #define MONGOC_ENCRYPT_ALGORITHM_INDEXED "Indexed"
+   // (Experimental: See below)
    #define MONGOC_ENCRYPT_ALGORITHM_UNINDEXED "Unindexed"
 
 Identifies the algorithm to use for encryption. Valid values of ``algorithm`` are:
 
-* "AEAD_AES_256_CBC_HMAC_SHA_512-Random" for randomized encryption.
-* "AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic" for deterministic (queryable) encryption.
-* "Indexed" for indexed encryption.
-* "Unindexed" for unindexed encryption.
+``"AEAD_AES_256_CBC_HMAC_SHA_512-Random"``
+
+   for randomized encryption.
+
+``"AEAD_AES_256_CBC_HMAC_SHA_512-Deterministic"``
+
+   for deterministic (queryable) encryption.
+
+``"Indexed"``
+
+   for indexed encryption.
+
+   .. note:: |qenc:opt-is-experimental|
+
+``"Unindexed"``
+
+   for unindexed encryption.
+
+   .. note:: |qenc:opt-is-experimental|
 
 Parameters
 ----------
diff --git a/src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_contention_factor.rst b/src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_contention_factor.rst
@@ -12,6 +12,9 @@ Synopsis
     mongoc_client_encryption_encrypt_opts_set_contention_factor (
         mongoc_client_encryption_encrypt_opts_t *opts, int64_t contention_factor);
 
+.. important:: |qenc:api-is-experimental|
+.. versionadded:: 1.22.0
+
 Sets a contention factor for explicit encryption.
 Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Indexed".
 It is an error to set the contention factor when algorithm is not "Indexed".
diff --git a/src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_query_type.rst b/src/libmongoc/doc/mongoc_client_encryption_encrypt_opts_set_query_type.rst
@@ -14,6 +14,9 @@ Synopsis
     mongoc_client_encryption_encrypt_opts_set_query_type (
         mongoc_client_encryption_encrypt_opts_t *opts, mongoc_encrypt_query_type_t query_type);
 
+.. important:: |qenc:api-is-experimental|
+.. versionadded:: 1.22.0
+
 Sets a query type for explicit encryption.
 Only applies when the algorithm set by :symbol:`mongoc_client_encryption_encrypt_opts_set_algorithm()` is "Indexed".
 It is an error to set the query type when algorithm is not "Indexed".
diff --git a/src/libmongoc/doc/queryable-encryption.rst b/src/libmongoc/doc/queryable-encryption.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+##################################
+Experimental: Queryable Encryption
+##################################
+
+MongoDB 6.0 introduces *Queryable Encryption* as a Public Technical Preview.
+This API is still experimental and subject to breaking changes!
+
+APIs that are part of Queryable Encryption will be marked as experimental, and
+one should not rely on their stability.
