             return try self.value(at: fieldIndex, as: valueType)
         }
     }
-
+    
+    /// Represents the set of tuples containing the data returned in a result.
+    /// (You might think of the tuples as the "rows" of data returned by the result, 
+    /// though technically they are not rows since they may not exactly match 
+    /// rows in a table.)
+    /// 
+    /// A `TupleView` for a `PGResult` can be accessed through its `tuples` 
+    /// property. It is an `Int`-indexed `RandomAccessCollection` whose elements 
+    /// are all `Tuple` instances describing individual tuples returned by the result.
+    /// 
+    /// As a `RandomAccessCollection`, you can access the number of tuples 
+    /// through the `count` property and obtain a particular tuple by 
+    /// subscripting the `TupleView`. You can also loop over it with `for` or use 
+    /// higher-order operations like `map`.
+    /// 
+    /// - Warning: The `TupleView` struct's properties and subscripts rely  
+    ///              on the `PGResult` the instance is derived from to access the 
+    ///              information. Do not use a `TupleView` from a `PGResult` which 
+    ///              you have already `clear()`ed.
     public struct TupleView: _IntIndexedCollection, RandomAccessCollection {
         fileprivate let result: PGResult
         
+        /// The index after the index of the last tuple.
+        /// 
         /// - RecommendedOver: `PQntuples`
         public var endIndex: Int {
             return Int(PQntuples(result.pointer))
         }
         
+        /// Retrieves the `i`th tuple in the result.
+        /// 
+        /// - Precondition: There are at least `i + 1` tuples in the result.
         public subscript(i: Int) -> Tuple {
             precondition(i < endIndex, "Index out of bounds")
             return Tuple(result: result, index: i)

import libpq

extension PGResult {
    public var tuples: TupleView {
        return TupleView(result: self)
    }
    
    public struct Tuple: _IntIndexedCollection, RandomAccessCollection {
        fileprivate let result: PGResult
        public let index: Int
        
        public var endIndex: Int {
            return result.fields.endIndex
        }
        
        /// - RecommendedOver: `PQgetvalue`, `PQgetisnull`, `PQgetlength`
        public subscript(field: Field) -> PGRawValue? {
            precondition(field.result === result, "Used a Field from one Result to access a Tuple from another Result")

        }
        
        // WORKAROUND: Swift does not support generic subscripts 
        // 
        /// Accesses the value of `field` in this tuple, converting it to `valueType`,  
        /// or `nil` if the field is `NULL`.
        /// 
        /// - Parameter field: The field to access.
        /// - Parameter valueType: The type to convert the field's value into.
        /// - Throws: If the conversion to `valueType` fails.
        /// - Precondition: `field` is a `Field` from the same `PGResult` used to 
        ///                   access the `Tuple`.
        /// 
        /// - RecommendedOver: `PGResult.Tuple.subscript(_:)`
        public func value<Value: PGValue>(in field: Field, as valueType: Value.Type) throws -> Value? {
            let rawValue = self[field]
            return try rawValue.map(valueType.init(rawPGValue:))
        }
        
        // WORKAROUND: Swift does not support generic subscripts 
        // 
        /// Accesses the value of the field at `fieldIndex` in this tuple, converting 
        /// it to `valueType`, or `nil` if the field is `NULL`.
        /// 
        /// - Parameter fieldIndex: The index of the field to access.
        /// - Parameter valueType: The type to convert the field's value into.
        /// - Throws: If the conversion to `valueType` fails.
        /// - Precondition: `fieldIndex` is the index of a valid `Field` in the result.
        /// 
        /// - RecommendedOver: `PGResult.Tuple.subscript(_:)`
        public func value<Value: PGValue>(at fieldIndex: Int, as valueType: Value.Type) throws -> Value? {
            let field = result.fields[fieldIndex]
            return try self.value(in: field, as: valueType)
        }
        
        // WORKAROUND: Swift does not support generic subscripts 
        // 
        /// Accesses the value of the field with `fieldName` in this tuple, converting 
        /// it to `valueType`. The value is `.some(nil)` if the field is `NULL`, or 
        /// `nil` if no field for `fieldName` exists.
        /// 
        /// - Parameter fieldName: The name of the field to access.
        /// - Parameter valueType: The type to convert the field's value into.
        /// - Throws: If the conversion to `valueType` fails.
        /// - Precondition: `fieldIndex` is the index of a valid `Field` in the result.
        /// 
        /// - RecommendedOver: `PGResult.Tuple.subscript(_:)`
        public func value<Value: PGValue>(for fieldName: String, as valueType: Value.Type) throws -> Value?? {
            guard let fieldIndex = result.fields.index(of: fieldName) else {
                return nil
