Add docstrings to all public types

postgres/_authentication_failure_reason.pony

@@ -5,7 +5,16 @@ type AuthenticationFailureReason is
   | UnsupportedAuthenticationMethod )
 
 primitive InvalidAuthenticationSpecification
+  """
+  The server rejected the connection due to an invalid authentication
+  specification (SQLSTATE 28000), such as a nonexistent user or a user
+  not permitted to connect to the requested database.
+  """
+
 primitive InvalidPassword
+  """
+  The server rejected the provided password (SQLSTATE 28P01).
+  """
 
 primitive ServerVerificationFailed
   """

postgres/error_response_message.pony

@@ -1,4 +1,10 @@
 class val ErrorResponseMessage
+  """
+  A fatal error message from the PostgreSQL server. Contains all standard
+  error fields defined by the PostgreSQL protocol (severity, SQLSTATE code,
+  human-readable message, and optional detail fields). Delivered via
+  receiver failure callbacks when a server-side operation fails.
+  """
   let severity: String
   let localized_severity: (String | None)
   let code: String

postgres/field.pony

@@ -1,4 +1,9 @@
 class val Field is Equatable[Field]
+  """
+  A single column value within a `Row`. Contains the column name and the
+  value converted to the appropriate Pony type based on the PostgreSQL type
+  OID (see `FieldDataTypes`). NULL values are represented as `None`.
+  """
   let name: String
   let value: FieldDataTypes
 

postgres/query.pony

@@ -1,8 +1 @@
 type Query is (SimpleQuery | PreparedQuery | NamedPreparedQuery)
-  """
-  A query that can be executed via `Session.execute()`. SimpleQuery uses the
-  simple query protocol (unparameterized); PreparedQuery uses the extended
-  query protocol with an unnamed prepared statement (parameterized);
-  NamedPreparedQuery executes a previously prepared named statement with
-  parameters.
-  """

postgres/query_error.pony

@@ -1,4 +1,9 @@
 trait val ClientQueryError
+  """
+  A client-side error that prevented a query from being sent to the server.
+  Each subtype represents a specific pre-condition failure (session not open,
+  session closed, not authenticated, or malformed data).
+  """
 
 primitive SessionNeverOpened is ClientQueryError
   """

postgres/result.pony

@@ -1,7 +1,17 @@
 trait val Result
+  """
+  The result of a successfully executed query. Subtypes distinguish between
+  queries that return rows (`ResultSet`), queries that modify rows
+  (`RowModifying`), and queries that do neither (`SimpleResult`).
+  """
   fun query(): Query
 
 class val ResultSet is Result
+  """
+  A query result containing rows. Returned for SELECT and other row-returning
+  statements. Provides access to the returned `Rows` and the command tag
+  string (e.g., "SELECT").
+  """
   let _query: Query
   let _rows: Rows
   let _command: String
@@ -24,6 +34,10 @@ class val ResultSet is Result
     _command
 
 class val SimpleResult is Result
+  """
+  A query result for statements that return no rows and report no row count.
+  Returned for empty queries (the `EmptyQueryResponse` case).
+  """
   let _query: Query
 
   new val create(query': Query) =>
@@ -33,6 +47,10 @@ class val SimpleResult is Result
     _query
 
 class val RowModifying is Result
+  """
+  A query result for statements that modify rows (INSERT, UPDATE, DELETE).
+  Provides the command tag string and the number of rows affected.
+  """
   let _query: Query
   let _command: String
   let _impacted: USize

postgres/row.pony

@@ -1,4 +1,8 @@
 class val Row is Equatable[Row]
+  """
+  A single row from a query result. Contains an ordered array of `Field`
+  values corresponding to the columns in the `RowDescription`.
+  """
   let fields: Array[Field] val
 
   new val create(fields': Array[Field] val) =>

postgres/rows.pony

@@ -1,4 +1,8 @@
 class val Rows is Equatable[Rows]
+  """
+  An ordered collection of `Row` values from a query result. Supports indexed
+  access via `apply()` and iteration via `values()`.
+  """
   let _rows: Array[Row] val
 
   new val create(rows': Array[Row] val) =>
@@ -41,6 +45,10 @@ class val Rows is Equatable[Rows]
     RowIterator._create(_rows)
 
 class RowIterator is Iterator[Row]
+  """
+  An iterator over the rows in a `Rows` collection. Supports rewinding to
+  iterate multiple times. Obtained via `Rows.values()`.
+  """
   let _array: Array[Row] val
   var _i: USize
 

postgres/session.pony

@@ -5,6 +5,19 @@ use "ssl/crypto"
 use "ssl/net"
 
 actor Session is (lori.TCPConnectionActor & lori.ClientLifecycleEventReceiver)
+  """
+  The main entry point for interacting with a PostgreSQL server. Manages the
+  connection lifecycle — connecting, authenticating, executing queries, and
+  shutting down — as a state machine.
+
+  Create a session with `ServerConnectInfo` and `DatabaseConnectInfo`.
+  Connection and authentication events are delivered to a
+  `SessionStatusNotify` receiver.
+
+  Query execution is serialized: only one operation is in flight at a time.
+  Additional calls to `execute`, `prepare`, `copy_in`, or `copy_out` are
+  queued and dispatched in order.
+  """
   var state: _SessionState
   var _tcp_connection: lori.TCPConnection = lori.TCPConnection.none()
   let _server_connect_info: ServerConnectInfo

postgres/session_status_notify.pony

@@ -1,4 +1,10 @@
 interface tag SessionStatusNotify
+  """
+  Receives session lifecycle events: connection, authentication, transaction
+  status changes, asynchronous notifications, server notices, and parameter
+  status updates. All callbacks have default no-op implementations, so
+  consumers only need to override the events they care about.
+  """
   be pg_session_connected(session: Session) =>
     """
     Called when we have connected to the server but haven't yet tried to
@@ -60,9 +66,6 @@ interface tag SessionStatusNotify
     these during connection startup for all reporting parameters (server_version,
     client_encoding, standard_conforming_strings, etc.) and again whenever a
     SET command changes one.
-
-    The callback has a default no-op implementation, so existing code is
-    unaffected.
     """
     None
 

postgres/simple_query.pony

@@ -1,4 +1,9 @@
 class val SimpleQuery
+  """
+  An unparameterized query using PostgreSQL's simple query protocol. The query
+  string may contain multiple semicolon-separated SQL statements; each
+  statement produces its own result delivered to the `ResultReceiver`.
+  """
   let string: String
 
   new val create(string': String) =>