Add docs clarifying that FieldDescriptions may return nil

#1634

conn.go

@@ -648,6 +648,9 @@ type QueryRewriter interface {
 // returned Rows even if an error is returned. The error will be the available in rows.Err() after rows are closed. It
 // is allowed to ignore the error returned from Query and handle it in Rows.
 //
+// It is possible for a call of FieldDescriptions on the returned Rows to return nil even if the Query call did not
+// return an error.
+//
 // It is possible for a query to return one or more rows before encountering an error. In most cases the rows should be
 // collected before processing rather than processed while receiving each row. This avoids the possibility of the
 // application processing rows from a query that the server rejected. The CollectRows function is useful here.

pgconn/pgconn.go

@@ -1479,7 +1479,8 @@ func (rr *ResultReader) NextRow() bool {
 }
 
 // FieldDescriptions returns the field descriptions for the current result set. The returned slice is only valid until
-// the ResultReader is closed.
+// the ResultReader is closed. It may return nil (for example, if the query did not return a result set or an error was
+// encountered.)
 func (rr *ResultReader) FieldDescriptions() []FieldDescription {
 	return rr.fieldDescriptions
 }

rows.go

@@ -28,12 +28,16 @@ type Rows interface {
 	// to call Close after rows is already closed.
 	Close()
 
-	// Err returns any error that occurred while reading.
+	// Err returns any error that occurred while reading. Err must only be called after the Rows is closed (either by
+	// calling Close or by Next returning false). If it is called early it may return nil even if there was an error
+	// executing the query.
 	Err() error
 
 	// CommandTag returns the command tag from this query. It is only available after Rows is closed.
 	CommandTag() pgconn.CommandTag
 
+	// FieldDescriptions returns the field descriptions of the columns. It may return nil. In particular this can occur
+	// when there was an error executing the query.
 	FieldDescriptions() []pgconn.FieldDescription
 
 	// Next prepares the next row for reading. It returns true if there is another