Documentation

src/fb-cpp/Blob.h

@@ -69,7 +69,14 @@ namespace fbcpp
 	///
 	enum class BlobStorage : std::uint8_t
 	{
+		///
+		/// Blob is stored in the main database file.
+		///
 		MAIN = isc_bpb_storage_main,
+
+		///
+		/// Blob is stored in temporary storage and will not persist beyond the transaction.
+		///
 		TEMPORARY = isc_bpb_storage_temp
 	};
 
@@ -78,7 +85,14 @@ namespace fbcpp
 	///
 	enum class BlobType : std::uint8_t
 	{
+		///
+		/// Blob is stored and accessed as discrete segments.
+		///
 		SEGMENTED = isc_bpb_type_segmented,
+
+		///
+		/// Blob is treated as a continuous stream of bytes.
+		///
 		STREAM = isc_bpb_type_stream
 	};
 
@@ -231,8 +245,19 @@ namespace fbcpp
 	///
 	enum class BlobSeekMode : int
 	{
+		///
+		/// Offset is relative to the beginning of the blob.
+		///
 		FROM_BEGIN = 0,
+
+		///
+		/// Offset is relative to the current position in the blob.
+		///
 		FROM_CURRENT = blb_seek_relative,
+
+		///
+		/// Offset is relative to the end of the blob.
+		///
 		FROM_END = blb_seek_from_tail
 	};
 

src/fb-cpp/Descriptor.h

@@ -38,25 +38,104 @@ namespace fbcpp
 	///
 	enum class DescriptorOriginalType : unsigned
 	{
+		///
+		/// Null type indicator.
+		///
 		NULL_TYPE = SQL_NULL,
+
+		///
+		/// Fixed-length text.
+		///
 		TEXT = SQL_TEXT,
+
+		///
+		/// Variable-length text.
+		///
 		VARYING = SQL_VARYING,
+
+		///
+		/// 16-bit signed integer.
+		///
 		SHORT = SQL_SHORT,
+
+		///
+		/// 32-bit signed integer.
+		///
 		LONG = SQL_LONG,
+
+		///
+		/// Single-precision floating point.
+		///
 		FLOAT = SQL_FLOAT,
+
+		///
+		/// Double-precision floating point.
+		///
 		DOUBLE = SQL_DOUBLE,
+
+		///
+		/// Timestamp without time zone.
+		///
 		TIMESTAMP = SQL_TIMESTAMP,
+
+		///
+		/// Binary large object.
+		///
 		BLOB = SQL_BLOB,
+
+		///
+		/// Time of day without time zone.
+		///
 		TIME = SQL_TYPE_TIME,
+
+		///
+		/// Calendar date.
+		///
 		DATE = SQL_TYPE_DATE,
+
+		///
+		/// 64-bit signed integer.
+		///
 		INT64 = SQL_INT64,
+
+		///
+		/// Timestamp with time zone.
+		///
 		TIMESTAMP_TZ = SQL_TIMESTAMP_TZ,
+
+		///
+		/// Extended timestamp with time zone.
+		///
 		TIMESTAMP_TZ_EX = SQL_TIMESTAMP_TZ_EX,
+
+		///
+		/// Time of day with time zone.
+		///
 		TIME_TZ = SQL_TIME_TZ,
+
+		///
+		/// Extended time of day with time zone.
+		///
 		TIME_TZ_EX = SQL_TIME_TZ_EX,
+
+		///
+		/// 128-bit signed integer.
+		///
 		INT128 = SQL_INT128,
+
+		///
+		/// 16-digit decimal floating point.
+		///
 		DEC16 = SQL_DEC16,
+
+		///
+		/// 34-digit decimal floating point.
+		///
 		DEC34 = SQL_DEC34,
+
+		///
+		/// Boolean value.
+		///
 		BOOLEAN = SQL_BOOLEAN,
 	};
 
@@ -65,24 +144,99 @@ namespace fbcpp
 	///
 	enum class DescriptorAdjustedType : unsigned
 	{
+		///
+		/// Null type indicator.
+		///
 		NULL_TYPE = SQL_NULL,
+
+		///
+		/// String type (variable-length).
+		///
 		STRING = SQL_VARYING,
+
+		///
+		/// 16-bit signed integer.
+		///
 		INT16 = SQL_SHORT,
+
+		///
+		/// 32-bit signed integer.
+		///
 		INT32 = SQL_LONG,
+
+		///
+		/// Single-precision floating point.
+		///
 		FLOAT = SQL_FLOAT,
+
+		///
+		/// Double-precision floating point.
+		///
 		DOUBLE = SQL_DOUBLE,
+
+		///
+		/// Timestamp without time zone.
+		///
 		TIMESTAMP = SQL_TIMESTAMP,
+
+		///
+		/// Binary large object.
+		///
 		BLOB = SQL_BLOB,
+
+		///
+		/// Time of day without time zone.
+		///
 		TIME = SQL_TYPE_TIME,
+
+		///
+		/// Calendar date.
+		///
 		DATE = SQL_TYPE_DATE,
+
+		///
+		/// 64-bit signed integer.
+		///
 		INT64 = SQL_INT64,
+
+		///
+		/// Timestamp with time zone.
+		///
 		TIMESTAMP_TZ = SQL_TIMESTAMP_TZ,
+
+		///
+		/// Extended timestamp with time zone.
+		///
 		TIMESTAMP_TZ_EX = SQL_TIMESTAMP_TZ_EX,
+
+		///
+		/// Time of day with time zone.
+		///
 		TIME_TZ = SQL_TIME_TZ,
+
+		///
+		/// Extended time of day with time zone.
+		///
 		TIME_TZ_EX = SQL_TIME_TZ_EX,
+
+		///
+		/// 128-bit signed integer.
+		///
 		INT128 = SQL_INT128,
+
+		///
+		/// 16-digit decimal floating point.
+		///
 		DECFLOAT16 = SQL_DEC16,
+
+		///
+		/// 34-digit decimal floating point.
+		///
 		DECFLOAT34 = SQL_DEC34,
+
+		///
+		/// Boolean value.
+		///
 		BOOLEAN = SQL_BOOLEAN,
 	};
 
@@ -91,12 +245,39 @@ namespace fbcpp
 	///
 	struct Descriptor final
 	{
+		///
+		/// Original SQL type as reported by Firebird.
+		///
 		DescriptorOriginalType originalType;
+
+		///
+		/// Adjusted type after normalization for easier handling.
+		///
 		DescriptorAdjustedType adjustedType;
+
+		///
+		/// Decimal scale for numeric types; zero for non-numeric types.
+		///
 		int scale;
+
+		///
+		/// Length in bytes of the column or parameter data.
+		///
 		unsigned length;
+
+		///
+		/// Byte offset of this field within the message buffer.
+		///
 		unsigned offset;
+
+		///
+		/// Byte offset of the null indicator within the message buffer.
+		///
 		unsigned nullOffset;
+
+		///
+		/// Indicates whether the column or parameter can contain null values.
+		///
 		bool isNullable;
 		// FIXME: more things
 	};

src/fb-cpp/Exception.h

@@ -176,22 +176,34 @@ namespace fbcpp::impl
 ///
 namespace fbcpp
 {
+	///
+	/// Base exception class for all fb-cpp exceptions.
+	///
 	class FbCppException : public std::runtime_error
 	{
 	public:
 		using std::runtime_error::runtime_error;
 
+		///
+		/// Constructs an FbCppException with the specified error message.
+		///
 		explicit FbCppException(const std::string& message)
 			: std::runtime_error{message}
 		{
 		}
 	};
 
+	///
+	/// Exception thrown when a Firebird database operation fails.
+	///
 	class DatabaseException final : public FbCppException
 	{
 	public:
 		using FbCppException::FbCppException;
 
+		///
+		/// Constructs a DatabaseException from a Firebird status vector.
+		///
 		explicit DatabaseException(Client& client, const std::intptr_t* status)
 			: FbCppException{buildMessage(client, status)}
 		{

src/fb-cpp/SmartPtrs.h

@@ -45,16 +45,25 @@ namespace fbcpp
 		};
 	}  // namespace impl
 
+	///
+	/// Unique pointer type for Firebird disposable objects.
+	///
 	template <typename T>
 	using FbUniquePtr = std::unique_ptr<T, impl::FbDisposeDeleter>;
 
+	///
+	/// Creates a unique pointer for a Firebird disposable object.
+	///
 	template <typename T>
 	FbUniquePtr<T> fbUnique(T* obj) noexcept
 	{
 		return FbUniquePtr<T>{obj};
 	}
 
 	// FIXME: Review every usage to see if is not leaking one reference count.
+	///
+	/// Reference-counted smart pointer for Firebird objects using addRef/release semantics.
+	///
 	template <typename T>
 	class FbRef final
 	{
@@ -212,6 +221,9 @@ namespace fbcpp
 		T* ptr;
 	};
 
+	///
+	/// Creates a reference-counted smart pointer for a Firebird object.
+	///
 	template <typename T>
 	FbRef<T> fbRef(T* arg) noexcept
 	{