Clean up docs for new ParseConfigOptions feature

config.go

@@ -65,8 +65,10 @@ type Config struct {
 	createdByParseConfig bool // Used to enforce created by ParseConfig rule.
 }
 
-//Congig Options such as getsslpassword function
+// ParseConfigOptions contains options that control how a config is built such as getsslpassword.
 type ParseConfigOptions struct {
+	// GetSSLPassword gets the password to decrypt a SSL client certificate. This is analogous to the the libpq function
+	// PQsetSSLKeyPassHook_OpenSSL.
 	GetSSLPassword GetSSLPasswordFunc
 }
 
@@ -139,16 +141,10 @@ func NetworkAddress(host string, port uint16) (network, address string) {
 	return network, address
 }
 
-// ParseConfig builds a *Config when sslpasswordcallback function is not provided
+// ParseConfig builds a *Config from connString with similar behavior to the PostgreSQL standard C library libpq. It
-func ParseConfig(connString string) (*Config, error) {
+// uses the same defaults as libpq (e.g. port=5432) and understands most PG* environment variables. ParseConfig closely
-	var parseConfigOptions ParseConfigOptions
+// matches the parsing behavior of libpq. connString may either be in URL format or keyword = value format (DSN style).
-	return ParseConfigWithOptions(connString, parseConfigOptions)
+// See https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING for details. connString also may be
-}
-
-// ParseConfig builds a *Config with similar behavior to the PostgreSQL standard C library libpq. It uses the same
-// defaults as libpq (e.g. port=5432) and understands most PG* environment variables. ParseConfig closely matches
-// the parsing behavior of libpq. connString may either be in URL format or keyword = value format (DSN style). See
-// https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING for details. connString also may be
 // empty to only read from the environment. If a password is not supplied it will attempt to read the .pgpass file.
 //
 //   # Example DSN
@@ -172,22 +168,22 @@ func ParseConfig(connString string) (*Config, error) {
 // ParseConfig currently recognizes the following environment variable and their parameter key word equivalents passed
 // via database URL or DSN:
 //
-// 	 PGHOST
+//   PGHOST
-// 	 PGPORT
+//   PGPORT
-// 	 PGDATABASE
+//   PGDATABASE
-// 	 PGUSER
+//   PGUSER
-// 	 PGPASSWORD
+//   PGPASSWORD
-// 	 PGPASSFILE
+//   PGPASSFILE
-// 	 PGSERVICE
+//   PGSERVICE
-// 	 PGSERVICEFILE
+//   PGSERVICEFILE
-// 	 PGSSLMODE
+//   PGSSLMODE
-// 	 PGSSLCERT
+//   PGSSLCERT
-// 	 PGSSLKEY
+//   PGSSLKEY
-// 	 PGSSLROOTCERT
+//   PGSSLROOTCERT
 //   PGSSLPASSWORD
-// 	 PGAPPNAME
+//   PGAPPNAME
-// 	 PGCONNECT_TIMEOUT
+//   PGCONNECT_TIMEOUT
-// 	 PGTARGETSESSIONATTRS
+//   PGTARGETSESSIONATTRS
 //
 // See http://www.postgresql.org/docs/11/static/libpq-envars.html for details on the meaning of environment variables.
 //
@@ -207,8 +203,7 @@ func ParseConfig(connString string) (*Config, error) {
 // sslmode "prefer" this means it will first try the main Config settings which use TLS, then it will try the fallback
 // which does not use TLS. This can lead to an unexpected unencrypted connection if the main TLS config is manually
 // changed later but the unencrypted fallback is present. Ensure there are no stale fallbacks when manually setting
-// TLCConfig.
+// TLSConfig.
-// ParseConfigOptions options for parse config
 //
 // Other known differences with libpq:
 //
@@ -217,12 +212,20 @@ func ParseConfig(connString string) (*Config, error) {
 //
 // In addition, ParseConfig accepts the following options:
 //
-// 	min_read_buffer_size
+//  min_read_buffer_size
-// 		The minimum size of the internal read buffer. Default 8192.
+//    The minimum size of the internal read buffer. Default 8192.
-// 	servicefile
+//  servicefile
-// 		libpq only reads servicefile from the PGSERVICEFILE environment variable. ParseConfig accepts servicefile as a
+//    libpq only reads servicefile from the PGSERVICEFILE environment variable. ParseConfig accepts servicefile as a
-// 		part of the connection string.
+//    part of the connection string.
-func ParseConfigWithOptions(connString string, parseConfigOptions ParseConfigOptions) (*Config, error) {
+func ParseConfig(connString string) (*Config, error) {
+	var parseConfigOptions ParseConfigOptions
+	return ParseConfigWithOptions(connString, parseConfigOptions)
+}
+
+// ParseConfigWithOptions builds a *Config from connString and options with similar behavior to the PostgreSQL standard
+// C library libpq. options contains settings that cannot be specified in a connString such as providing a function to
+// get the SSL password.
+func ParseConfigWithOptions(connString string, options ParseConfigOptions) (*Config, error) {
 	defaultSettings := defaultSettings()
 	envSettings := parseEnvSettings()
 
@@ -342,7 +345,7 @@ func ParseConfigWithOptions(connString string, parseConfigOptions ParseConfigOpt
 			tlsConfigs = append(tlsConfigs, nil)
 		} else {
 			var err error
-			tlsConfigs, err = configTLS(settings, host, parseConfigOptions)
+			tlsConfigs, err = configTLS(settings, host, options)
 			if err != nil {
 				return nil, &parseConfigError{connString: connString, msg: "failed to configure TLS", err: err}
 			}

pgconn.go

@@ -109,9 +109,9 @@ func Connect(ctx context.Context, connString string) (*PgConn, error) {
 	return ConnectConfig(ctx, config)
 }
 
-// Connect establishes a connection to a PostgreSQL server using the environment
+// Connect establishes a connection to a PostgreSQL server using the environment and connString (in URL or DSN format)
-// and connString (in URL or DSN format) and ParseConfigOptions
+// and ParseConfigOptions to provide additional configuration. See documentation for ParseConfig for details. ctx can be
-// to provide configuration. See documentation for ParseConfig for details. ctx can be used to cancel a connect attempt.
+// used to cancel a connect attempt.
 func ConnectWithOptions(ctx context.Context, connString string, parseConfigOptions ParseConfigOptions) (*PgConn, error) {
 	config, err := ParseConfigWithOptions(connString, parseConfigOptions)
 	if err != nil {

pgconn_test.go

@@ -53,7 +53,7 @@ func TestConnect(t *testing.T) {
 	}
 }
 
-func TestConnectWithOption(t *testing.T) {
+func TestConnectWithOptions(t *testing.T) {
 	tests := []struct {
 		name string
 		env  string