From d3e8b9177be194a2aed7d4af0af20c7441607e9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Thu, 26 Feb 2026 19:57:58 +0100 Subject: [PATCH 01/17] cassandra.h: Add missing `@public @memberof` --- include/cassandra.h | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/include/cassandra.h b/include/cassandra.h index 526c690b..2fce8738 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -6350,6 +6350,8 @@ cass_data_type_free(CassDataType* data_type); /** * Gets the value type of the specified data type. * + * @public @memberof CassDataType + * * @param[in] data_type * @return The value type */ @@ -6359,6 +6361,8 @@ cass_data_type_type(const CassDataType* data_type); /** * Gets whether a data type is frozen. * + * @public @memberof CassDataType + * * @param[in] data_type * @return cass_true if the data type is frozen, otherwise cass_false. */ @@ -6370,6 +6374,8 @@ cass_data_type_is_frozen(const CassDataType* data_type); * * Note: Only valid for UDT data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[out] type_name * @param[out] type_name_length @@ -6385,6 +6391,8 @@ cass_data_type_type_name(const CassDataType* data_type, * * Note: Only valid for UDT data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] type_name * @return CASS_OK if successful, otherwise an error occurred. @@ -6414,6 +6422,8 @@ cass_data_type_set_type_name_n(CassDataType* data_type, * * Note: Only valid for UDT data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[out] keyspace * @param[out] keyspace_length @@ -6429,6 +6439,8 @@ cass_data_type_keyspace(const CassDataType* data_type, * * Note: Only valid for UDT data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] keyspace * @return CASS_OK if successful, otherwise an error occurred. @@ -6458,6 +6470,8 @@ cass_data_type_set_keyspace_n(CassDataType* data_type, * * Note: Only valid for custom data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[out] class_name * @param[out] class_name_length @@ -6473,6 +6487,8 @@ cass_data_type_class_name(const CassDataType* data_type, * * Note: Only valid for custom data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] class_name * @return CASS_OK if successful, otherwise an error occurred. @@ -6503,6 +6519,8 @@ cass_data_type_set_class_name_n(CassDataType* data_type, * * Note: Only valid for UDT, tuple and collection data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @return Returns the number of sub-data types */ @@ -6531,6 +6549,8 @@ cass_data_sub_type_count(const CassDataType* data_type)); * * Note: Only valid for UDT, tuple and collection data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] index * @return Returns a reference to a child data type. Do not free this @@ -6546,6 +6566,8 @@ cass_data_type_sub_data_type(const CassDataType* data_type, * * Note: Only valid for UDT data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] name * @return Returns a reference to a child data type. Do not free this @@ -6579,6 +6601,8 @@ cass_data_type_sub_data_type_by_name_n(const CassDataType* data_type, * * Note: Only valid for UDT data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] index * @param[out] name @@ -6596,6 +6620,8 @@ cass_data_type_sub_type_name(const CassDataType* data_type, * * Note: Only valid for tuple and collection data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] sub_data_type * @return CASS_OK if successful, otherwise an error occurred. @@ -6609,6 +6635,8 @@ cass_data_type_add_sub_type(CassDataType* data_type, * * Note: Only valid for UDT data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] name * @param[in] sub_data_type @@ -6625,6 +6653,8 @@ cass_data_type_add_sub_type_by_name(CassDataType* data_type, * * Note: Only valid for UDT data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] name * @param[in] name_length @@ -6642,6 +6672,8 @@ cass_data_type_add_sub_type_by_name_n(CassDataType* data_type, * * Note: Only valid for tuple and collection data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] sub_value_type * @return CASS_OK if successful, otherwise an error occurred. @@ -6656,6 +6688,8 @@ cass_data_type_add_sub_value_type(CassDataType* data_type, * * Note: Only valid for UDT data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] name * @param[in] sub_value_type @@ -6672,6 +6706,8 @@ cass_data_type_add_sub_value_type_by_name(CassDataType* data_type, * * Note: Only valid for UDT data types. * + * @public @memberof CassDataType + * * @param[in] data_type * @param[in] name * @param[in] name_length @@ -6733,6 +6769,8 @@ cass_collection_free(CassCollection* collection); /** * Gets the data type of a collection. * + * @public @memberof CassCollection + * * @param[in] collection * @return Returns a reference to the data type of the collection. Do not free * this reference as it is bound to the lifetime of the collection. @@ -7042,6 +7080,8 @@ cass_tuple_free(CassTuple* tuple); /** * Gets the data type of a tuple. * + * @public @memberof CassTuple + * * @param[in] tuple * @return Returns a reference to the data type of the tuple. Do not free * this reference as it is bound to the lifetime of the tuple. @@ -7385,6 +7425,8 @@ cass_user_type_free(CassUserType* user_type); /** * Gets the data type of a user defined type. * + * @public @memberof CassUserType + * * @param[in] user_type * @return Returns a reference to the data type of the user defined type. * Do not free this reference as it is bound to the lifetime of the @@ -9805,6 +9847,8 @@ cass_timestamp_gen_monotonic_new(); * Same as cass_timestamp_gen_monotonic_new(), but with settings for controlling * warnings about clock skew. * + * @public @memberof CassTimestampGen + * * @param warning_threshold_us The amount of clock skew, in microseconds, that * must be detected before a warning is triggered. A threshold less than 0 can * be used to disable warnings. From 5bbd519c4694a02b4f7c1c697ee9f6e89ab181c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Thu, 26 Feb 2026 19:58:49 +0100 Subject: [PATCH 02/17] cass_batch_set_tracing: Correct doc category --- include/cassandra.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/cassandra.h b/include/cassandra.h index 2fce8738..43878d20 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -6221,7 +6221,7 @@ cass_batch_set_custom_payload(CassBatch* batch, /** * Sets whether the batch should use tracing. * - * @public @memberof CassStatement + * @public @memberof CassBatch * * @param[in] batch * @param[in] enabled From ed489fdd2df1c75edfe414993630ebd10a073669 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Thu, 26 Feb 2026 20:01:53 +0100 Subject: [PATCH 03/17] cassandra.h: Remove stale comment This was a duplicate of doc comment for cass_data_type_sub_type_count function. --- include/cassandra.h | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/include/cassandra.h b/include/cassandra.h index 43878d20..636b3091 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -6533,16 +6533,6 @@ cass_data_type_sub_type_count(const CassDataType* data_type); CASS_EXPORT CASS_DEPRECATED(size_t cass_data_sub_type_count(const CassDataType* data_type)); -/** - * Gets the sub-data type count of a UDT (user defined type), tuple - * or collection. - * - * Note: Only valid for UDT, tuple and collection data types. - * - * @param[in] data_type - * @return Returns the number of sub-data types - */ - /** * Gets the sub-data type of a UDT (user defined type), tuple or collection at * the specified index. From 8af7b4e01030b41d3f66c94edfba279dfdd9ab12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 10:51:22 +0100 Subject: [PATCH 04/17] cassandra.h: Fix doxygen warnings There were some errors in the documentation: missing parameters docs, wrong parameter name, @return docs for functions returning void. All of this was resulting in Doxygen warnings. This commit fixes all those issues. --- include/cassandra.h | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/include/cassandra.h b/include/cassandra.h index 636b3091..a6456109 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -714,7 +714,7 @@ typedef enum CassError_ { /** * A callback that's notified when the future is set. * - * @param[in] message + * @param[in] future * @param[in] data user defined data provided when the callback * was registered. * @@ -1102,6 +1102,8 @@ cass_execution_profile_set_load_balance_rack_aware(CassExecProfile* profile, * @param[in] profile * @param[in] local_dc * @param[in] local_dc_length + * @param[in] local_rack + * @param[in] local_rack_length * @return same cass_execution_profile_set_load_balance_rack_aware() * * @see cass_execution_profile_set_load_balance_rack_aware() @@ -1987,7 +1989,6 @@ cass_cluster_set_credentials(CassCluster* cluster, * @param[in] username_length * @param[in] password * @param[in] password_length - * @return same as cass_cluster_set_credentials() * * @see cass_cluster_set_credentials(); */ @@ -2094,6 +2095,8 @@ cass_cluster_set_load_balance_rack_aware(CassCluster* cluster, * @param[in] cluster * @param[in] local_dc * @param[in] local_dc_length + * @param[in] local_rack + * @param[in] local_rack_length * @return same as cass_cluster_set_load_balance_dc_aware() * * @see cass_cluster_set_load_balance_dc_aware() @@ -2234,7 +2237,6 @@ cass_cluster_set_whitelist_filtering(CassCluster* cluster, * @param[in] cluster * @param[in] hosts * @param[in] hosts_length - * @return same as cass_cluster_set_whitelist_filtering() * * @see cass_cluster_set_whitelist_filtering() */ @@ -2276,7 +2278,6 @@ cass_cluster_set_blacklist_filtering(CassCluster* cluster, * @param[in] cluster * @param[in] hosts * @param[in] hosts_length - * @return same as cass_cluster_set_blacklist_filtering() * * @see cass_cluster_set_blacklist_filtering() */ @@ -2310,7 +2311,6 @@ cass_cluster_set_whitelist_dc_filtering(CassCluster* cluster, * @param[in] cluster * @param[in] dcs * @param[in] dcs_length - * @return same as cass_cluster_set_whitelist_dc_filtering() * * @see cass_cluster_set_whitelist_dc_filtering() */ @@ -2344,7 +2344,6 @@ cass_cluster_set_blacklist_dc_filtering(CassCluster* cluster, * @param[in] cluster * @param[in] dcs * @param[in] dcs_length - * @return same as cass_cluster_set_blacklist_dc_filtering() * * @see cass_cluster_set_blacklist_dc_filtering() */ @@ -4163,7 +4162,6 @@ cass_ssl_add_trusted_cert_n(CassSsl* ssl, * * @param[in] ssl * @param[in] flags - * @return CASS_OK if successful, otherwise an error occurred * * @see cass_cluster_set_use_hostname_resolution() */ From 953b259a04673c662b454f75d80bfa8bc710a9da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 11:01:48 +0100 Subject: [PATCH 05/17] conf.py: Don't use paths as strings This resulted in a warning, but would become a hard error in Sphinx v9. This commit fixes the warning by using python paths as they were intended, instead of string concatenation. After this commit there is only 1 warning left when building docs, and it is not in our code (Breathe extension will need to fix it). --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 60b9bf76..1f0f9292 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -112,7 +112,7 @@ def _generate_structs(outdir, structs, project): """Write structs docs in the designated outdir folder""" for obj in structs: - with open(outdir + "/struct." + obj + ".rst", "w") as t_file: + with open(outdir / f"struct.{obj}.rst", "w") as t_file: t_file.write( obj + "\n" @@ -143,7 +143,7 @@ def _generate_doxygen_rst(xmldir, outdir): def generate_doxygen(app): DOXYGEN_XML_DIR = breathe_projects[breathe_default_project] - _generate_doxygen_rst(DOXYGEN_XML_DIR, app.builder.srcdir + "/api") + _generate_doxygen_rst(DOXYGEN_XML_DIR, app.builder.srcdir / "api") # -- Options for sitemap extension From d9d6a8a979676a927cbb697d422ef7c526237969 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Mon, 2 Mar 2026 16:58:10 +0100 Subject: [PATCH 06/17] conf.py: Add support for Doxygen groups We want to add all items from cassandra.h that are missing from rendered docs. For many, we can't use `@memberof`, because they don't really fit any struct. A good tool for this are Doxygen groups, but right now our documentation won't render them. This commit adds support for rendering them. --- docs/source/conf.py | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 1f0f9292..3cb51e4b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -3,6 +3,7 @@ import re import sys import warnings +import xml.etree.ElementTree as ET from datetime import date from sphinx_scylladb_theme.utils import multiversion_regex_builder @@ -125,10 +126,29 @@ def _generate_structs(outdir, structs, project): ) +def _generate_groups(outdir, groups, project): + """Write structs docs in the designated outdir folder""" + for obj in groups: + with open(outdir / f"group.{obj}.rst", "w") as t_file: + t_file.write( + obj + + "\n" + + "=" * len(obj) + + "\n\n" + + ".. doxygengroup:: " + + obj + + "\n :project: " + + breathe_default_project + + "\n :content-only:" + ) + + def _generate_doxygen_rst(xmldir, outdir): """Autogenerate doxygen docs in the designated outdir folder""" structs = [] - files = os.listdir(os.path.join(os.path.dirname(__file__), xmldir)) + groups = [] + xml_path = os.path.join(os.path.dirname(__file__), xmldir) + files = os.listdir(xml_path) for file_name in files: if "struct" in file_name and "__" not in file_name: structs.append( @@ -138,7 +158,15 @@ def _generate_doxygen_rst(xmldir, outdir): .title() .replace(" ", "") ) + elif file_name.startswith("group__") and file_name.endswith(".xml"): + tree = ET.parse(os.path.join(xml_path, file_name)) + root = tree.getroot() + compoundname = root.find(".//compoundname") + if compoundname is not None and compoundname.text: + group_name = compoundname.text + groups.append(group_name) _generate_structs(outdir, structs, breathe_default_project) + _generate_groups(outdir, groups, breathe_default_project) def generate_doxygen(app): From dc6ceb733b2c27597fe2c9cd309de9b40f89dfb7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 11:15:30 +0100 Subject: [PATCH 07/17] Expose freestanding functions Some of them don't really belong to any struct, and so have not been exported. The solution is to introduce new groups for them. For now, I introduced two: one for logging-related stuff, one for everything else. --- include/cassandra.h | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/include/cassandra.h b/include/cassandra.h index a6456109..3fbfd3a6 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -903,6 +903,18 @@ typedef enum CassCompressionType_ { CASS_COMPRESSION_NONE } CassCompressionType; +/** + * @defgroup Logging Logging + * + * Functions for configuring logging in the driver. + */ + +/** + * @defgroup Miscellaneous Miscellaneous + * + * Utility and miscellaneous functions. + */ + /*********************************************************************************** * * Execution Profile @@ -10082,6 +10094,8 @@ cass_custom_payload_remove_n(CassCustomPayload* payload, /** * Gets the string for a consistency. * + * @ingroup Miscellaneous + * * @param[in] consistency * @return A null-terminated string for the consistency. * Example: "ALL", "ONE", "QUORUM", etc. @@ -10097,6 +10111,8 @@ cass_consistency_string(CassConsistency consistency); /** * Gets the string for a write type. * + * @ingroup Miscellaneous + * * @param[in] write_type * @return A null-terminated string for the write type. * Example: "BATCH", "SIMPLE", "COUNTER", etc. @@ -10113,6 +10129,8 @@ cass_write_type_string(CassWriteType write_type); /** * Gets a description for an error code. * + * @ingroup Miscellaneous + * * @param[in] error * @return A null-terminated string describing the error. */ @@ -10128,6 +10146,8 @@ cass_error_desc(CassError error); /** * Sets the log level. * + * @ingroup Logging + * * Note: This needs to be done before any call that might log, such as * any of the cass_cluster_*() or cass_ssl_*() functions. * @@ -10141,6 +10161,8 @@ cass_log_set_level(CassLogLevel log_level); /** * Sets a callback for handling logging events. * + * @ingroup Logging + * * Note: This needs to be done before any call that might log, such as * any of the cass_cluster_*() or cass_ssl_*() functions. * @@ -10157,6 +10179,8 @@ cass_log_set_callback(CassLogCallback callback, /** * Analogous getter - useful for restoring logger to previous values. * + * @ingroup Logging + * * @param[out] callback_out Current logging callback. Must point to a valid memory area. * @param[out] data_out Current Logger instance. Must point to a valid memory area. */ @@ -10166,6 +10190,8 @@ cass_log_get_callback_and_data(CassLogCallback* callback_out, void** data_out); /** * Gets the string for a log level. * + * @ingroup Logging + * * @param[in] log_level * @return A null-terminated string for the log level. * Example: "ERROR", "WARN", "INFO", etc. @@ -10256,6 +10282,8 @@ cass_inet_from_string_n(const char* str, * represents the number of days since the Epoch (1970-01-01) with the Epoch centered at * the value 2^31. * + * @ingroup Miscellaneous + * * @param[in] epoch_secs * @return the number of days since the date -5877641-06-23 */ @@ -10266,6 +10294,8 @@ cass_date_from_epoch(cass_int64_t epoch_secs); * Converts a unix timestamp (in seconds) to the Cassandra "time" type. The "time" type * represents the number of nanoseconds since midnight (range 0 to 86399999999999). * + * @ingroup Miscellaneous + * * @param[in] epoch_secs * @return nanoseconds since midnight */ @@ -10275,6 +10305,8 @@ cass_time_from_epoch(cass_int64_t epoch_secs); /** * Combines the Cassandra "date" and "time" types to Epoch time in seconds. * + * @ingroup Miscellaneous + * * @param[in] date * @param[in] time * @return Epoch time in seconds. Negative times are possible if the date @@ -10293,6 +10325,8 @@ cass_date_time_to_epoch(cass_uint32_t date, /** * Set custom allocation functions. * + * @ingroup Miscellaneous + * * Warning: This function is not yet implemented. * * Note: This is not thread-safe. The allocation functions must be set From fafe906fb734a1d8ca2a995da02d8d086abe706a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 12:39:20 +0100 Subject: [PATCH 08/17] Introduce BasicTypes group It contains stuff like int aliases, that were missing from docs until now. --- include/cassandra.h | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/include/cassandra.h b/include/cassandra.h index 3fbfd3a6..c68f3b04 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -60,26 +60,65 @@ extern "C" { #endif +/** + * @ingroup BasicTypes + */ typedef enum { cass_false = 0, cass_true = 1 } cass_bool_t; +/** + * @ingroup BasicTypes + */ typedef float cass_float_t; +/** + * @ingroup BasicTypes + */ typedef double cass_double_t; +/** + * @ingroup BasicTypes + */ typedef int8_t cass_int8_t; +/** + * @ingroup BasicTypes + */ typedef uint8_t cass_uint8_t; +/** + * @ingroup BasicTypes + */ typedef int16_t cass_int16_t; +/** + * @ingroup BasicTypes + */ typedef uint16_t cass_uint16_t; +/** + * @ingroup BasicTypes + */ typedef int32_t cass_int32_t; +/** + * @ingroup BasicTypes + */ typedef uint32_t cass_uint32_t; +/** + * @ingroup BasicTypes + */ typedef int64_t cass_int64_t; +/** + * @ingroup BasicTypes + */ typedef uint64_t cass_uint64_t; #define CASS_UINT64_MAX 18446744073709551615ULL +/** + * @ingroup BasicTypes + */ typedef cass_uint8_t cass_byte_t; +/** + * @ingroup BasicTypes + */ typedef cass_uint64_t cass_duration_t; /** @@ -903,6 +942,12 @@ typedef enum CassCompressionType_ { CASS_COMPRESSION_NONE } CassCompressionType; +/** + * @defgroup BasicTypes Basic types + * + * Primitive type aliases used throughout the driver API. + */ + /** * @defgroup Logging Logging * From c1f164a7bf75328704ff7a62da946c67aee3ec46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 12:41:35 +0100 Subject: [PATCH 09/17] Introduce CassError group It contains CassError enum and related types: CassWriteType, CassErrorSource, and functions that operate on them. --- include/cassandra.h | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/include/cassandra.h b/include/cassandra.h index c68f3b04..8da4698b 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -507,6 +507,9 @@ typedef enum CassConsistency_ { #define CASS_CONSISTENCY_MAP CASS_CONSISTENCY_MAPPING /* Deprecated */ /* @endcond */ +/** + * @ingroup CassError + */ typedef enum CassWriteType_ { CASS_WRITE_TYPE_UNKNOWN, CASS_WRITE_TYPE_SIMPLE, @@ -664,6 +667,9 @@ typedef enum CassProtocolVersion_ { driver with DataStax Enterprise */ } CassProtocolVersion; +/** + * @ingroup CassError + */ typedef enum CassErrorSource_ { CASS_ERROR_SOURCE_NONE, CASS_ERROR_SOURCE_LIB, @@ -740,6 +746,9 @@ typedef enum CassErrorSource_ { #define CASS_ERROR(source, code) ((source << 24) | code) +/** + * @ingroup CassError + */ typedef enum CassError_ { CASS_OK = 0, #define XX_ERROR(source, name, code, _) name = CASS_ERROR(source, code), @@ -954,6 +963,12 @@ typedef enum CassCompressionType_ { * Functions for configuring logging in the driver. */ +/** + * @defgroup CassError CassError + * + * Error codes and related types. + */ + /** * @defgroup Miscellaneous Miscellaneous * @@ -10156,7 +10171,7 @@ cass_consistency_string(CassConsistency consistency); /** * Gets the string for a write type. * - * @ingroup Miscellaneous + * @ingroup CassError * * @param[in] write_type * @return A null-terminated string for the write type. @@ -10174,7 +10189,7 @@ cass_write_type_string(CassWriteType write_type); /** * Gets a description for an error code. * - * @ingroup Miscellaneous + * @ingroup CassError * * @param[in] error * @return A null-terminated string describing the error. From cbb3aa8534f92a44b9485e6782371c39bf2759cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 12:43:07 +0100 Subject: [PATCH 10/17] Introduce CustomAllocator group It contains types used in cass_alloc_set_functions function, and the function itself. --- include/cassandra.h | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/include/cassandra.h b/include/cassandra.h index 8da4698b..560c1c8a 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -807,6 +807,8 @@ typedef void (*CassLogCallback)(const CassLogMessage* message, * A custom malloc function. This function should allocate "size" bytes and * return a pointer to that memory * + * @ingroup CustomAllocator + * * @param[in] size The size of the memory to allocate * * @see CassFreeFunction @@ -819,6 +821,8 @@ typedef void* (*CassMallocFunction)(size_t size); * memory pointed to by "ptr". If the memory cannot be resized then new memory * should be allocated and contain the contents of the original memory at "ptr". * + * @ingroup CustomAllocator + * * @param[in] ptr A pointer to the original memory. If NULL it should behave the * same as "CassMallocFunction" * @param[in] size The size of the memory to allocate/resize. @@ -834,6 +838,8 @@ typedef void* (*CassReallocFunction)(void* ptr, size_t size); * "ptr" that was previously allocated by a "CassMallocFunction" or * "CassReallocFunction" function. * + * @ingroup CustomAllocator + * * @param[in] ptr A pointer to memory that should be deallocated. If NULL then * this will perform no operation. * @@ -969,6 +975,12 @@ typedef enum CassCompressionType_ { * Error codes and related types. */ +/** + * @defgroup CustomAllocator Custom allocator + * + * Custom memory allocation functions. + */ + /** * @defgroup Miscellaneous Miscellaneous * @@ -10385,7 +10397,7 @@ cass_date_time_to_epoch(cass_uint32_t date, /** * Set custom allocation functions. * - * @ingroup Miscellaneous + * @ingroup CustomAllocator * * Warning: This function is not yet implemented. * From 96404419030cebc234d35bf677140e9d8a39a687 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 12:46:21 +0100 Subject: [PATCH 11/17] CassAuthenticatorCallbacks: Add type aliases Fields of CassAuthenticatorCallbacks used type aliases that were not documented. This commit adds them to docs of this struct. --- include/cassandra.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/include/cassandra.h b/include/cassandra.h index 560c1c8a..baca7c75 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -859,6 +859,8 @@ typedef struct CassAuthenticator_ CassAuthenticator; /** * A callback used to initiate an authentication exchange. * + * @memberof CassAuthenticatorCallbacks + * * Use cass_authenticator_set_response() to set the response token. * * Use cass_authenticator_set_error() if an error occurred during @@ -874,6 +876,8 @@ typedef void (*CassAuthenticatorInitialCallback)(CassAuthenticator* auth, * A callback used when an authentication challenge initiated * by the server. * + * @memberof CassAuthenticatorCallbacks + * * Use cass_authenticator_set_response() to set the response token. * * Use cass_authenticator_set_error() if an error occurred during the @@ -892,6 +896,8 @@ typedef void (*CassAuthenticatorChallengeCallback)(CassAuthenticator* auth, * A callback used to indicate the success of the authentication * exchange. * + * @memberof CassAuthenticatorCallbacks + * * Use cass_authenticator_set_error() if an error occurred while evaluating * the success token. * @@ -909,6 +915,8 @@ typedef void (*CassAuthenticatorSuccessCallback)(CassAuthenticator* auth, * the process of the authentication exchange. This is called after * the termination of the exchange regardless of the outcome. * + * @memberof CassAuthenticatorCallbacks + * * @param[in] auth * @param[in] data */ @@ -918,6 +926,8 @@ typedef void (*CassAuthenticatorCleanupCallback)(CassAuthenticator* auth, /** * A callback used to cleanup resources. * + * @memberof CassAuthenticatorCallbacks + * * @param[in] data */ typedef void (*CassAuthenticatorDataCleanupCallback)(void* data); From 88907020610898512724257a40b8b847f27c670e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 12:47:47 +0100 Subject: [PATCH 12/17] Add some types to Miscellaneous I don't see a better place for them. --- include/cassandra.h | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/include/cassandra.h b/include/cassandra.h index baca7c75..b3b3f6bf 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -590,6 +590,9 @@ typedef enum CassValueType_ { /* @endcond */ } CassValueType; +/** + * @ingroup Miscellaneous + */ typedef enum CassClusteringOrder_ { CASS_CLUSTERING_ORDER_NONE, CASS_CLUSTERING_ORDER_ASC, @@ -655,6 +658,9 @@ typedef enum CassSslVerifyFlags_ { CASS_SSL_VERIFY_PEER_IDENTITY_DNS = 0x04 } CassSslVerifyFlags; +/** + * @ingroup Miscellaneous + */ typedef enum CassProtocolVersion_ { CASS_PROTOCOL_VERSION_V1 = 0x01, /**< Deprecated */ CASS_PROTOCOL_VERSION_V2 = 0x02, /**< Deprecated */ @@ -942,6 +948,9 @@ typedef struct CassAuthenticatorCallbacks_ { CassAuthenticatorCleanupCallback cleanup_callback; } CassAuthenticatorCallbacks; +/** + * @ingroup Miscellaneous + */ typedef enum CassHostListenerEvent_ { CASS_HOST_LISTENER_EVENT_UP, CASS_HOST_LISTENER_EVENT_DOWN, @@ -952,6 +961,8 @@ typedef enum CassHostListenerEvent_ { /** * A callback used to indicate the host state for a node in the cluster. * + * @ingroup Miscellaneous + * * @param[in] event * @param[in] address * @param[in] data @@ -961,6 +972,9 @@ typedef void(*CassHostListenerCallback)(CassHostListenerEvent event, const CassInet address, void* data); +/** + * @ingroup Miscellaneous + */ typedef enum CassCompressionType_ { CASS_COMPRESSION_LZ4, CASS_COMPRESSION_SNAPPY, From 2c7b989a6683e099f20e5ade65b46affe2e99fb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 12:49:37 +0100 Subject: [PATCH 13/17] Introduce CassConsistency group CassConsistency appears in many functions, operating on various types. Because of that I think it deserves its own section. --- include/cassandra.h | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/include/cassandra.h b/include/cassandra.h index b3b3f6bf..740f940b 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -474,6 +474,9 @@ typedef struct CassSpeculativeExecutionMetrics_ { cass_double_t percentage; /**< Fraction of requests that are aborted speculative retries */ } CassSpeculativeExecutionMetrics; +/** + * @ingroup CassConsistency + */ typedef enum CassConsistency_ { CASS_CONSISTENCY_UNKNOWN = 0xFFFF, CASS_CONSISTENCY_ANY = 0x0000, @@ -999,6 +1002,12 @@ typedef enum CassCompressionType_ { * Error codes and related types. */ +/** + * @defgroup CassConsistency CassConsistency + * + * Consistency levels for queries. + */ + /** * @defgroup CustomAllocator Custom allocator * @@ -10190,7 +10199,7 @@ cass_custom_payload_remove_n(CassCustomPayload* payload, /** * Gets the string for a consistency. * - * @ingroup Miscellaneous + * @ingroup CassConsistency * * @param[in] consistency * @return A null-terminated string for the consistency. From ca9f1e9c872ec59d92356d37859032ef17f55d3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 12:52:08 +0100 Subject: [PATCH 14/17] Introduce CassValueType section in docs CassValueTypes appears in functions belonging to more than one type, and quite many of them, so I think it deserves its own section. --- include/cassandra.h | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/include/cassandra.h b/include/cassandra.h index 740f940b..555015f7 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -583,6 +583,9 @@ typedef enum CassIndexType_ { XX(CASS_VALUE_TYPE_UDT, 0x0030, "", "") \ XX(CASS_VALUE_TYPE_TUPLE, 0x0031, "tuple", "org.apache.cassandra.db.marshal.TupleType") +/** + * @ingroup CassValueType + */ typedef enum CassValueType_ { CASS_VALUE_TYPE_UNKNOWN = 0xFFFF, #define XX_VALUE_TYPE(name, type, cql, klass) name = type, @@ -1008,6 +1011,12 @@ typedef enum CassCompressionType_ { * Consistency levels for queries. */ +/** + * @defgroup CassValueType CassValueType + * + * Data type representations for values. + */ + /** * @defgroup CustomAllocator Custom allocator * From 9cff95d4ce216b6417b7718e78a0f04b0247e676 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 12:54:34 +0100 Subject: [PATCH 15/17] Docs: Add missing types Some enums were not present in docs. I added them to relevant section. --- include/cassandra.h | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/include/cassandra.h b/include/cassandra.h index 555015f7..e3ed71e5 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -539,6 +539,9 @@ typedef enum CassWriteType_ { #define CASS_WRITE_TYPE_MAP CASS_WRITE_TYPE_MAPPING /* Deprecated */ /* @endcond */ +/** + * @memberof CassColumnMeta + */ typedef enum CassColumnType_ { CASS_COLUMN_TYPE_REGULAR, CASS_COLUMN_TYPE_PARTITION_KEY, @@ -547,6 +550,9 @@ typedef enum CassColumnType_ { CASS_COLUMN_TYPE_COMPACT_VALUE } CassColumnType; +/** + * @memberof CassIndexMeta + */ typedef enum CassIndexType_ { CASS_INDEX_TYPE_UNKNOWN, CASS_INDEX_TYPE_KEYS, @@ -605,18 +611,27 @@ typedef enum CassClusteringOrder_ { CASS_CLUSTERING_ORDER_DESC } CassClusteringOrder; +/** + * @memberof CassCollection + */ typedef enum CassCollectionType_ { CASS_COLLECTION_TYPE_LIST = CASS_VALUE_TYPE_LIST, CASS_COLLECTION_TYPE_MAP = CASS_VALUE_TYPE_MAP, CASS_COLLECTION_TYPE_SET = CASS_VALUE_TYPE_SET } CassCollectionType; +/** + * @memberof CassBatch + */ typedef enum CassBatchType_ { CASS_BATCH_TYPE_LOGGED = 0x00, CASS_BATCH_TYPE_UNLOGGED = 0x01, CASS_BATCH_TYPE_COUNTER = 0x02 } CassBatchType; +/** + * @memberof CassIterator + */ typedef enum CassIteratorType_ { CASS_ITERATOR_TYPE_RESULT, CASS_ITERATOR_TYPE_ROW, @@ -657,6 +672,9 @@ typedef enum CassLogLevel_ { /* @endcond */ } CassLogLevel; +/** + * @memberof CassSsl + */ typedef enum CassSslVerifyFlags_ { CASS_SSL_VERIFY_NONE = 0x00, CASS_SSL_VERIFY_PEER_CERT = 0x01, @@ -774,6 +792,8 @@ typedef enum CassError_ { /** * A callback that's notified when the future is set. * + * @memberof CassFuture + * * @param[in] future * @param[in] data user defined data provided when the callback * was registered. From 466cb493a82d0738337069a51c7ee0ab9412b057 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 27 Feb 2026 13:05:14 +0100 Subject: [PATCH 16/17] Docs: add missing types to Logging section This commit adds missing logging-related types to the logging section. A struct can't be duplicated in docs, and CassLogMessage is a struct so it had its own section. To fix that, I adjusted logic in conf.py: now, if a struct is present in some group, it will not get its own section. --- docs/source/conf.py | 22 ++++++++++++++-------- include/cassandra.h | 7 +++++++ 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 3cb51e4b..07104204 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -147,24 +147,30 @@ def _generate_doxygen_rst(xmldir, outdir): """Autogenerate doxygen docs in the designated outdir folder""" structs = [] groups = [] + group_structs = set() xml_path = os.path.join(os.path.dirname(__file__), xmldir) files = os.listdir(xml_path) + for file_name in files: + if file_name.startswith("group__") and file_name.endswith(".xml"): + tree = ET.parse(os.path.join(xml_path, file_name)) + root = tree.getroot() + compoundname = root.find(".//compoundname") + if compoundname is not None and compoundname.text: + group_name = compoundname.text + groups.append(group_name) + for inner in root.iter("innerclass"): + group_structs.add(inner.text) for file_name in files: if "struct" in file_name and "__" not in file_name: - structs.append( + name = ( file_name.replace("struct_", "") .replace("_", " ") .replace(".xml", "") .title() .replace(" ", "") ) - elif file_name.startswith("group__") and file_name.endswith(".xml"): - tree = ET.parse(os.path.join(xml_path, file_name)) - root = tree.getroot() - compoundname = root.find(".//compoundname") - if compoundname is not None and compoundname.text: - group_name = compoundname.text - groups.append(group_name) + if name not in group_structs: + structs.append(name) _generate_structs(outdir, structs, breathe_default_project) _generate_groups(outdir, groups, breathe_default_project) diff --git a/include/cassandra.h b/include/cassandra.h index e3ed71e5..e1d8db8a 100644 --- a/include/cassandra.h +++ b/include/cassandra.h @@ -663,6 +663,9 @@ typedef enum CassIteratorType_ { #define CASS_LOG_LEVEL_MAP CASS_LOG_LEVEL_MAPPING /* Deprecated */ /* @endcond */ +/** + * @ingroup Logging + */ typedef enum CassLogLevel_ { #define XX_LOG(log_level, _) log_level, CASS_LOG_LEVEL_MAPPING(XX_LOG) @@ -810,6 +813,8 @@ typedef void (*CassFutureCallback)(CassFuture* future, /** * A log message. + * + * @ingroup Logging */ typedef struct CassLogMessage_ { /** @@ -826,6 +831,8 @@ typedef struct CassLogMessage_ { /** * A callback that's used to handle logging. * + * @ingroup Logging + * * @param[in] message * @param[in] data user defined data provided when the callback * was registered. From 239ebd7ba4f353adbd34c2d1ec06a7445fc59a6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Mon, 2 Mar 2026 17:57:39 +0100 Subject: [PATCH 17/17] docs/Makefile: proper clean Before that `make clean` didn't clean all files produced while building docs. This commit fixes that. --- docs/Makefile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/Makefile b/docs/Makefile index d0b249be..90fbce18 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -34,6 +34,10 @@ pristine: clean .PHONY: clean clean: rm -rf $(BUILDDIR)/* + # We need to use git clean instead of rm -rf because + # source/api/index.rst is actually tracked by git. + git clean -f -d -X $(SOURCEDIR)/api/ + rm -rf ../doxygen/* # Generate output commands .PHONY: dirhtml