Add documentation

FossilOrigin-Name: e4c8de38e0a1c749ea0f05f594091f16d659a4d2e329672fb7208a4ff36a77cb

src/PGConnection.h

@@ -24,21 +24,65 @@
 
 OF_ASSUME_NONNULL_BEGIN
 
+/** @file */
+
+/**
+ * @brief A result row.
+ */
 typedef OFDictionary OF_GENERIC(OFString *, id) *PGRow;
 
+/**
+ * @class PGConnection PGConnection.h ObjPgSQL/ObjPgSQL.h
+ *
+ * @brief A connection to a database.
+ */
 @interface PGConnection: OFObject
 {
 	PGconn *_connection;
 	OFDictionary OF_GENERIC(OFString *, OFString *) *_parameters;
 }
 
+/**
+ * @brief The parameters for the database connection. See `PQconnectdb` in the
+ *	  PostgreSQL documentation.
+ */
 @property (nonatomic, copy)
     OFDictionary OF_GENERIC(OFString *, OFString *) *parameters;
 
+/**
+ * @brief Connects to the database.
+ *
+ * @throw PGConnectionFailedException The connection failed
+ */
 - (void)connect;
+
+/**
+ * @brief Resets the connection to the database.
+ */
 - (void)reset;
+
+/**
+ * @brief Closes the connection to the database.
+ */
 - (void)close;
+
+/**
+ * @brief Executes the specified command.
+ *
+ * @param command The command to execute
+ * @return The result of the command, if any
+ * @throw PGCommandFailedException Executing the command failed.
+ */
 - (nullable PGResult *)executeCommand: (OFConstantString *)command;
+
+/**
+ * @brief Executes the specified command.
+ *
+ * @param command The command to execute
+ * @param firstParameter First parameter for the command
+ * @return The result of the command, if any
+ * @throw PGCommandFailedException Executing the command failed.
+ */
 - (nullable PGResult *)executeCommand: (OFConstantString *)command
 			   parameters: (id)firstParameter, ... OF_SENTINEL;
 @end

src/PGConnection.m

@@ -22,11 +22,25 @@
 #import "PGResult+Private.h"
 
 #import "PGConnectionFailedException.h"
-#import "PGCommandFailedException.h"
+#import "PGExecuteCommandFailedException.h"
 
 @implementation PGConnection
 @synthesize pg_connection = _connection, parameters = _parameters;
 
+- (instancetype)init
+{
+	self = [super init];
+
+	@try {
+		_parameters = [[OFDictionary alloc] init];
+	} @catch (id e) {
+		[self release];
+		@throw e;
+	}
+
+	return self;
+}
+
 - (void)dealloc
 {
 	[_parameters release];
@@ -84,7 +98,7 @@
 
 	if (PQresultStatus(result) == PGRES_FATAL_ERROR) {
 		PQclear(result);
-		@throw [PGCommandFailedException
+		@throw [PGExecuteCommandFailedException
 		    exceptionWithConnection: self
 				    command: command];
 	}
@@ -97,7 +111,7 @@
 		return nil;
 	default:
 		PQclear(result);
-		@throw [PGCommandFailedException
+		@throw [PGExecuteCommandFailedException
 		    exceptionWithConnection: self
 				    command: command];
 	}
@@ -159,7 +173,7 @@
 		return nil;
 	default:
 		PQclear(result);
-		@throw [PGCommandFailedException
+		@throw [PGExecuteCommandFailedException
 		    exceptionWithConnection: self
 				    command: command];
 	}

src/PGResult.h

@@ -24,6 +24,14 @@ OF_ASSUME_NONNULL_BEGIN
 
 @class PGResultRow;
 
+/**
+ * @class PGResult PGResult.h ObjPgSQL/ObjPgSQL.h
+ *
+ * @brief A PostgreSQL result.
+ *
+ * This is a regular OFArray, where each entry in the array represents a result
+ * row.
+ */
 @interface PGResult: OFArray OF_GENERIC(PGResultRow *)
 {
 	PGresult *_result;

src/PGResultRow.h

@@ -24,6 +24,14 @@
 
 OF_ASSUME_NONNULL_BEGIN
 
+/**
+ * @class PGResult PGResult.h ObjPgSQL/ObjPgSQL.h
+ *
+ * @brief A PostgreSQL result row.
+ *
+ * This is a regular OFDictionary, where each entry in the dictionary
+ * represents a column of the result row.
+ */
 @interface PGResultRow: OFDictionary OF_GENERIC(OFString *, id)
 {
 	PGResult *_result;

src/exceptions/PGConnectionFailedException.h

@@ -20,6 +20,12 @@
 
 OF_ASSUME_NONNULL_BEGIN
 
+/**
+ * @class PGConnectionFailedException PGConnectionFailedException.h
+ *	  PgSQL/PgSQL.h
+ *
+ * @brief An exception indicating that connecting to the database failed.
+ */
 @interface PGConnectionFailedException: PGException
 @end
 

src/exceptions/PGConnectionFailedException.m

@@ -23,6 +23,6 @@
 {
 	return [OFString stringWithFormat:
 	    @"Establishing a PostgreSQL connection failed:\n%@\n"
-	    "Parameters: %@", _error, [_connection parameters]];
+	    "Parameters: %@", _errorMessage, [_connection parameters]];
 }
 @end

src/exceptions/PGException.h

@@ -22,15 +22,45 @@
 
 OF_ASSUME_NONNULL_BEGIN
 
+/**
+ * @class PGException PGException.h ObjPgSQL/ObjPgSQL.h
+ *
+ * @brief A PostgreSQL exception.
+ */
 @interface PGException: OFException
 {
 	PGConnection *_connection;
-	OFString *_error;
+	OFString *_errorMessage;
 }
 
+/**
+ * @brief The connection for which the exception occurred.
+ */
 @property (readonly, nonatomic) PGConnection *connection;
 
+/**
+ * @brief An error message for the exception.
+ */
+@property (readonly, nonatomic) OFString *errorMessage;
+
++ (instancetype)exception OF_UNAVAILABLE;
+
+/**
+ * @brief Creates a new PostgreSQL exception.
+ *
+ * @param connection The connection for which the exception occurred
+ * @return A new, autoreleased PostgreSQL exception
+ */
 + (instancetype)exceptionWithConnection: (PGConnection *)connection;
+
+- (instancetype)init OF_UNAVAILABLE;
+
+/**
+ * @brief Initializes an already allocated PostgreSQL exception.
+ *
+ * @param connection The connection for which the exception occurred
+ * @return An initialized PostgreSQL exception
+ */
 - (instancetype)initWithConnection: (PGConnection *)connection
     OF_DESIGNATED_INITIALIZER;
 @end

src/exceptions/PGException.m

@@ -20,20 +20,30 @@
 #import "PGConnection+Private.h"
 
 @implementation PGException
-@synthesize connection = _connection;
+@synthesize connection = _connection, errorMessage = _errorMessage;
+
++ (instancetype)exception
+{
+	OF_UNRECOGNIZED_SELECTOR
+}
 
 + (instancetype)exceptionWithConnection: (PGConnection *)connection
 {
 	return [[[self alloc] initWithConnection: connection] autorelease];
 }
 
+- (instancetype)init
+{
+	OF_INVALID_INIT_METHOD
+}
+
 - (instancetype)initWithConnection: (PGConnection *)connection
 {
 	self = [super init];
 
 	@try {
 		_connection = [connection retain];
-		_error = [[OFString alloc]
+		_errorMessage = [[OFString alloc]
 		    initWithCString: PQerrorMessage([_connection pg_connection])
 			   encoding: [OFLocale encoding]];
 	} @catch (id e) {
@@ -47,7 +57,7 @@
 - (void)dealloc
 {
 	[_connection release];
-	[_error release];
+	[_errorMessage release];
 
 	[super dealloc];
 }
@@ -55,6 +65,6 @@
 - (OFString *)description
 {
 	return [OFString stringWithFormat: @"A PostgreSQL operation failed: %@",
-					   _error];
+					   _errorMessage];
 }
 @end

src/exceptions/PGExecuteCommandFailedException.h

@@ -20,20 +20,46 @@
 
 OF_ASSUME_NONNULL_BEGIN
 
-@interface PGCommandFailedException: PGException
+/**
+ * @class PGExecuteCommandFailedException PGExecuteCommandFailedException.h
+ *	  ObjPgSQL/ObjPgSQL.h
+ *
+ * @brief An exception indicating that executing a command failed.
+ */
+@interface PGExecuteCommandFailedException: PGException
 {
-	OFString *_command;
+	OFConstantString *_command;
 }
 
-@property (readonly, nonatomic) OFString *command;
+/**
+ * @brief The command that could not be executed.
+ */
+@property (readonly, nonatomic) OFConstantString *command;
 
 + (instancetype)exceptionWithConnection: (PGConnection *)connection
     OF_UNAVAILABLE;
+
+/**
+ * @brief Creates a new execte command failed exception.
+ *
+ * @param connection The connection for which the command could not be executed
+ * @param command The command which could not be executed
+ * @return A new, autoreleased execute command failed exception
+ */
 + (instancetype)exceptionWithConnection: (PGConnection *)connection
-				command: (OFString *)command;
+				command: (OFConstantString *)command;
+
 - (instancetype)initWithConnection: (PGConnection *)connection OF_UNAVAILABLE;
+
+/**
+ * @brief Initializes an already allocated execte command failed exception.
+ *
+ * @param connection The connection for which the command could not be executed
+ * @param command The command which could not be executed
+ * @return An initialized execute command failed exception
+ */
 - (instancetype)initWithConnection: (PGConnection *)connection
-			   command: (OFString *)command
+			   command: (OFConstantString *)command
     OF_DESIGNATED_INITIALIZER;
 @end
 

src/exceptions/PGExecuteCommandFailedException.m

@@ -16,9 +16,9 @@
  * PERFORMANCE OF THIS SOFTWARE.
  */
 
-#import "PGCommandFailedException.h"
+#import "PGExecuteCommandFailedException.h"
 
-@implementation PGCommandFailedException
+@implementation PGExecuteCommandFailedException
 @synthesize command = _command;
 
 + (instancetype)exceptionWithConnection: (PGConnection *)connection
@@ -27,7 +27,7 @@
 }
 
 + (instancetype)exceptionWithConnection: (PGConnection *)connection
-				command: (OFString *)command
+				command: (OFConstantString *)command
 {
 	return [[[self alloc] initWithConnection: connection
 					 command: command] autorelease];
@@ -39,7 +39,7 @@
 }
 
 - (instancetype)initWithConnection: (PGConnection *)connection
-			   command: (OFString *)command
+			   command: (OFConstantString *)command
 {
 	self = [super initWithConnection: connection];
 
@@ -63,6 +63,7 @@
 - (OFString *)description
 {
 	return [OFString stringWithFormat: @"A PostgreSQL command failed: %@\n"
-					   @"Command: %@", _error, _command];
+					   @"Command: %@",
+					   _errorMessage, _command];
 }
 @end

src/exceptions/meson.build

@@ -1,5 +1,5 @@
 exceptions_sources = files(
-  'PGCommandFailedException.m',
   'PGConnectionFailedException.m',
   'PGException.m',
+  'PGExecuteCommandFailedException.m',
 )