Add missing connection statuses to docs

alvherre · alvherre · commit 095493a3771a · 2024-03-11T17:20:36.000+01:00
The list of connection statuses that PQstatus might return during an asynchronous connection attempt was outdated: 1. CONNECTION_SETENV is never returned anymore and is only part of the enum for backwards compatibility, so remove it from the docs. 2. CONNECTION_CHECK_STANDBY and CONNECTION_GSS_STARTUP were not listed, so add them. CONNECTION_NEEDED and CONNECTION_CHECK_TARGET are not listed in the docs on purpose, since these are internal states that can never be observed by a caller of PQstatus. Author: Jelte Fennema-Nio <postgres@jeltef.nl> Discussion: https://postgr.es/m/CAGECzQRb21spiiykQ48rzz8w+Hcykz+mB2_hxR65D9Qk6nnw=w@mail.gmail.com
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
@@ -428,11 +428,11 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
          </listitem>
         </varlistentry>
 
-        <varlistentry id="libpq-connection-setenv">
-         <term><symbol>CONNECTION_SETENV</symbol></term>
+        <varlistentry id="libpq-connection-gss-startup">
+         <term><symbol>CONNECTION_GSS_STARTUP</symbol></term>
          <listitem>
           <para>
-           Negotiating environment-driven parameter settings.
+           Negotiating GSS encryption.
           </para>
          </listitem>
         </varlistentry>
@@ -446,6 +446,15 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
          </listitem>
         </varlistentry>
 
+        <varlistentry id="libpq-connection-check-standby">
+         <term><symbol>CONNECTION_CHECK_STANDBY</symbol></term>
+         <listitem>
+          <para>
+           Checking if connection is to a server in standby mode.
+          </para>
+         </listitem>
+        </varlistentry>
+
         <varlistentry id="libpq-connection-consume">
          <term><symbol>CONNECTION_CONSUME</symbol></term>
          <listitem>
diff --git a/src/interfaces/libpq/libpq-fe.h b/src/interfaces/libpq/libpq-fe.h
@@ -73,11 +73,12 @@ typedef enum
 								 * backend startup. */
 	CONNECTION_SETENV,			/* This state is no longer used. */
 	CONNECTION_SSL_STARTUP,		/* Negotiating SSL. */
-	CONNECTION_NEEDED,			/* Internal state: connect() needed */
+	CONNECTION_NEEDED,			/* Internal state: connect() needed. */
 	CONNECTION_CHECK_WRITABLE,	/* Checking if session is read-write. */
 	CONNECTION_CONSUME,			/* Consuming any extra messages. */
 	CONNECTION_GSS_STARTUP,		/* Negotiating GSSAPI. */
-	CONNECTION_CHECK_TARGET,	/* Checking target server properties. */
+	CONNECTION_CHECK_TARGET,	/* Internal state: checking target server
+								 * properties. */
 	CONNECTION_CHECK_STANDBY	/* Checking if server is in standby mode. */
 } ConnStatusType;
 
