Further doc improvements.

Author: anthony-tuininga

doc/src/api_manual/module.rst

@@ -75,10 +75,9 @@ Oracledb Methods
     ``params`` parameter object. Similar precedence rules also apply to other
     values.
 
-    The ``dsn`` (data source name) parameter can be a string in the format
-    ``user/password@connect_string`` or can simply be the connect string (in
-    which case authentication credentials such as the username and password
-    need to be specified separately). See :ref:`connstr` for more information.
+    The ``dsn`` (data source name) parameter is an :ref:`Oracle Net Services
+    Connection String <connstr>`.  It can also be a string in the format
+    ``user/password@connect_string``.
 
     The ``pool`` parameter is expected to be a pool object. The use of this
     parameter is the equivalent of calling :meth:`ConnectionPool.acquire()`.
@@ -444,10 +443,9 @@ Oracledb Methods
     the ``params`` parameter object. Similar precedence rules also apply to
     other values.
 
-    The ``dsn`` (data source name) parameter can be a string in the format
-    ``user/password@connect_string`` or can simply be the connect string (in
-    which case authentication credentials such as the username and password
-    need to be specified separately). See :ref:`connstr` for more information.
+    The ``dsn`` (data source name) parameter is an :ref:`Oracle Net Services
+    Connection String <connstr>`.  It can also be a string in the format
+    ``user/password@connect_string``.
 
     The ``pool`` parameter is expected to be an AsyncConnectionPool object. The
     use of this parameter is the equivalent of calling
@@ -1086,8 +1084,7 @@ Oracledb Methods
     :ref:`ConnectionPool object <connpool>` for the pool.  See :ref:`Connection
     pooling <connpooling>` for more information.
 
-    This function is the equivalent of the `cx_Oracle.SessionPool()
-    <https://cx-oracle.readthedocs.io/en/latest/api_manual/module.html#cx_Oracle.SessionPool>`__
+    This function is the equivalent of the ``cx_Oracle.SessionPool()``
     function.  The use of ``SessionPool()`` has been deprecated in
     python-oracledb.
 
@@ -1551,7 +1548,7 @@ Oracledb Methods
     other values.
 
     The ``user``, ``password``, and ``dsn`` parameters are the same as for
-    :meth:`oracledb.connect_async()`.
+    :meth:`oracledb.connect()`.
 
     The ``pool_class`` parameter is expected to be an
     :ref:`AsyncConnectionPool Object <asyncconnpoolobj>` or a subclass of

doc/src/user_guide/appendix_b.rst

@@ -78,16 +78,18 @@ See :ref:`optnetfiles` and :ref:`optclientfiles` for more information.
 Connection Strings
 ------------------
 
-The python-oracledb Thin mode accepts connection strings in the same formats as
-the Oracle Client libraries used by Thick mode does, but not all Oracle Net
-keywords will be supported.
+Python-oracledb Thin mode accepts :ref:`Oracle Net Services connection strings
+<connstr>` in the same formats as the Oracle Client libraries used by Thick
+mode does, but not all keywords will be supported.
 
 The following table lists the parameters that are recognized in Thin mode
-either in Easy Connect Strings or in Full Connect Descriptor Strings that are
-either explicitly passed or referred to by a ``tnsnames.ora`` alias.  All
-unrecognized parameters are ignored.  The connection parameters shown can be
-used in :meth:`oracledb.connect()`, :meth:`oracledb.create_pool()`,
-:meth:`oracledb.ConnectParams()`, and :meth:`oracledb.PoolParams()`.
+either in :ref:`Easy Connect <easyconnect>` strings or in :ref:`Connect
+Descriptors <conndescriptor>` that are either explicitly passed, or are in a
+``tnsnames.ora`` file.  All unrecognized parameters are ignored.  The
+connection parameters shown can be used in :meth:`oracledb.connect()`,
+:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`,
+:meth:`oracledb.create_pool_async()`, :meth:`oracledb.ConnectParams()`, and
+:meth:`oracledb.PoolParams()`.
 
 .. list-table-with-summary::  Oracle Net Keywords Supported in the python-oracledb Thin Mode
     :header-rows: 1

doc/src/user_guide/appendix_c.rst

@@ -620,13 +620,12 @@ addition to the common :ref:`commonupgrade`:
 
    See :ref:`otherinit`.
 
-4. If the application is connecting using an :ref:`Oracle Net service name
-   <netservice>` from a ``tnsnames.ora`` file located in a "default" location
-   such as the Instant Client ``network/admin/`` subdirectory, in
-   ``$ORACLE_HOME/network/admin/``, or in
-   ``$ORACLE_BASE/homes/XYZ/network/admin/`` (in a read-only Oracle Database
-   home), then the configuration file directory must now explicitly be set as
-   shown above.
+4. If the application is connecting using a :ref:`TNS Alias <netservice>` from
+   a ``tnsnames.ora`` file located in a "default" location such as the Instant
+   Client ``network/admin/`` subdirectory, in ``$ORACLE_HOME/network/admin/``,
+   or in ``$ORACLE_BASE/homes/XYZ/network/admin/`` (in a read-only Oracle
+   Database home), then the configuration file directory must now explicitly be
+   set as shown in Step 2.
 
 5. Remove calls to :func:`oracledb.clientversion()` which is only available in
    the python-oracledb Thick mode.  Oracle Client libraries are not available