Improved documentation and code comments.

Author: anthony-tuininga

doc/src/conf.py

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 
 #------------------------------------------------------------------------------
-# Copyright (c) 2016, 2019 Oracle and/or its affiliates.  All rights reserved.
+# Copyright (c) 2016, 2020 Oracle and/or its affiliates.  All rights reserved.
 # This program is free software: you can modify it and/or redistribute it
 # under the terms of:
 #
@@ -18,12 +18,12 @@
 # the suffix used for all source files
 source_suffix = '.rst'
 
-# the name of the master document
+# the name of the main document
 master_doc = 'index'
 
 # general information about the project
 project = 'ODPI-C'
-copyright = '2016, 2019, Oracle and/or its affiliates. All rights reserved.'
+copyright = '2016, 2020, Oracle and/or its affiliates. All rights reserved.'
 author = 'Oracle'
 
 # the version info for the project, acts as replacement for |version| and

doc/src/index.rst

@@ -1,4 +1,4 @@
-.. ODPI-C documentation master file.
+.. ODPI-C documentation main file.
 
 Welcome to ODPI-C's |release| documentation!
 ============================================

doc/src/installation.rst

@@ -185,8 +185,10 @@ To run ODPI-C applications with Oracle Instant Client zip files:
    ``sqlnet.ora`` or ``oraaccess.xml``, put the files in an accessible
    directory. Then set the member
    :member:`dpiContextCreateParams.oracleClientConfigDir` when calling
-   :func:`dpiContext_createWithParams()`, or set the environment variable
-   ``TNS_ADMIN`` to that directory name.
+   :func:`dpiContext_createWithParams()`.
+
+   Alternatively, set the environment variable ``TNS_ADMIN`` to that directory
+   name.
 
    Alternatively, create a ``network/admin`` subdirectory of Instant Client, if
    it does not exist.  For example::
@@ -248,8 +250,10 @@ To run ODPI-C applications with Oracle Instant Client RPMs:
    ``sqlnet.ora`` or ``oraaccess.xml``, put the files in an accessible
    directory. Then set the member
    :member:`dpiContextCreateParams.oracleClientConfigDir` when calling
-   :func:`dpiContext_createWithParams()`, or set the environment variable
-   ``TNS_ADMIN`` to that directory name.
+   :func:`dpiContext_createWithParams()`.
+
+   Alternatively, set the environment variable ``TNS_ADMIN`` to that directory
+   name.
 
    Alternatively, create a ``network/admin`` subdirectory of Instant Client, if
    it does not exist.  For example::
@@ -348,42 +352,46 @@ To run ODPI-C applications with Oracle Instant Client zip files:
    ``instantclient-basic-windows.x64-19.6.0.0.0dbru.zip`` to
    ``C:\oracle\instantclient_19_6``.
 
-3. Either set this directory in the member
-   :member:`dpiContextCreateParams.oracleClientLibDir` when calling
-   :func:`dpiContext_createWithParams()`, or do the following.
+3. There are several alternative ways to tell your application where your Oracle
+   Instant Client libraries are.
 
-   Add this directory to the ``PATH`` environment variable. For example, on
-   Windows 7, update ``PATH`` in Control Panel -> System -> Advanced System
-   Settings -> Advanced -> Environment Variables -> System Variables -> PATH.
-   The Instant Client directory must occur in ``PATH`` before any other Oracle
-   directories.
+   * Set this directory in the member
+     :member:`dpiContextCreateParams.oracleClientLibDir` when calling
+     :func:`dpiContext_createWithParams()`.
 
-   Restart any open command prompt windows.
+   * Alternatively, move the unzipped Instant Client files to the same
+     directory as the ODPIC.DLL (or into the directory of the application's
+     binary, if ODPI-C is compiled into the application).
+
+   * Alternatively, add the Instant Client directory to the ``PATH``
+     environment variable. For example, on Windows 7, update ``PATH`` in
+     Control Panel -> System -> Advanced System Settings -> Advanced ->
+     Environment Variables -> System Variables -> PATH.  The Instant Client
+     directory must occur in ``PATH`` before any other Oracle directories.
 
-   To avoid interfering with existing tools that require other Oracle
-   Client versions, instead of updating the system-wide ``PATH`` variable, you
-   may prefer to write a batch file that sets ``PATH``, for example::
+     Restart any open command prompt windows.
 
-       REM mywrapper.bat
-       SET PATH=C:\oracle\instantclient_19_6;%PATH%
-       myapp %*
+     To avoid interfering with existing tools that require other Oracle Client
+     versions, instead of updating the system-wide ``PATH`` variable, you may
+     prefer to write a batch file that sets ``PATH``, for example::
 
-   Invoke this batch file everytime you want to run your application.
+         REM mywrapper.bat
+         SET PATH=C:\oracle\instantclient_19_6;%PATH%
+         myapp %*
 
-   Alternatively use ``SET`` to change your ``PATH`` in each command
-   prompt window before you run python.
+     Invoke this batch file every time you want to run your application.
 
-   Another option is to move the unzipped Instant Client files to the
-   same directory as the ODPIC.DLL (or into the directory of the
-   application's binary, if ODPI-C is compiled into application).  If
-   you do this, then ``PATH`` does not need to be set.
+     Or simply use ``SET`` to change your ``PATH`` in each command prompt window
+     before you run your application.
 
 4. If you use optional Oracle configuration files such as ``tnsnames.ora``,
    ``sqlnet.ora`` or ``oraaccess.xml``, put the files in an accessible
    directory. Then set the member
    :member:`dpiContextCreateParams.oracleClientConfigDir` when calling
-   :func:`dpiContext_createWithParams()`, or set the environment variable
-   ``TNS_ADMIN`` to that directory name.
+   :func:`dpiContext_createWithParams()`.
+
+   Alternatively, set the environment variable ``TNS_ADMIN`` to that directory
+   name.
 
    Alternatively, create a ``network\admin`` subdirectory of Instant Client, if
    it does not exist.  For example ``C:\oracle\instantclient_19_6\network\admin``.
@@ -445,42 +453,72 @@ To run ODPI-C applications with Oracle Instant Client zip files:
    application architecture.  Most applications use 64-bit.
 
 2. Unzip the package into a single directory that is accessible to your
-   application. For example, in Terminal you could unzip in your home directory::
+   application. For example, in Terminal you could unzip:
+
+   .. code-block:: shell
 
-       cd ~
-       unzip instantclient-basic-macos.x64-19.3.0.0.0dbru.zip
+       mkdir /opt/oracle
+       cd /opt/oracle
+       unzip /your/path/to/instantclient-basic-macos.x64-19.3.0.0.0dbru.zip
+
+3. There are several alternative ways to tell your application where your Oracle
+   Instant Client libraries are.
+
+   * Use the extracted directory for the member
+     :member:`dpiContextCreateParams.oracleClientLibDir` in a call to
+     :func:`dpiContext_createWithParams()`
+
+   * Alternatively, copy Oracle Instant Client to the directory containing the
+     ODPI-C module binary.  For example, if ``libodpic.dylib`` (or your binary
+     containing the ODPI-C code) is in ``~/myprograms`` you can then run ``ln -s
+     ~/instantclient_19_3/libclntsh.dylib ~/myprograms``.  You can also copy the
+     Instant Client libraries to that directory.
+
+   * Alternatively, set ``DYLD_LIBRARY_PATH`` to the Instant Client directory.  Note this
+     variable does not propagate to sub-shells.
+
+   * Alternatively, you might decide to compile the ODPI-C library with an RPATH
+     option like ``-Wl,-rpath,/usr/local/lib``.  Then you can link Oracle
+     Instant Client to this directory, for example::
 
-3. Either use this directory as the member
-   :member:`dpiContextCreateParams.oracleClientLibDir` is specified when calling
-   :func:`dpiContext_createWithParams()`, or do the following.
+         ln -s /opt/oracle/instantclient_19_3/libclntsh.dylib /usr/local/lib/
 
-   Add a link to ``$HOME/lib`` or ``/usr/local/lib`` to enable applications to
-   find Instant Client. If the ``lib`` sub-directory does not exist, you can
-   create it. For example::
+     Or, instead of a link you can copy the required OCI libraries. For example::
 
-       mkdir ~/lib
-       ln -s ~/instantclient_19_3/libclntsh.dylib ~/lib/
+         cp /opt/oracle/instantclient_19_3/{libclntsh.dylib.19.1,libclntshcore.dylib.19.1,libons.dylib,libnnz12.dylib,libociei.dylib} /usr/local/lib/
 
-   If you now run ``ls -l ~/lib/libclntsh.dylib`` you will see something like::
+   * Alternatively, on older versions of macOS, you could add a link to
+     ``$HOME/lib`` or ``/usr/local/lib`` to enable applications to find Instant
+     Client.  If the ``lib`` sub-directory does not exist, you can create
+     it. For example:
 
-       lrwxr-xr-x  1 yourname  staff  48 12 Nov 15:04 /Users/yourname/lib/libclntsh.dylib -> /Users/yourname/instantclient_19_3/libclntsh.dylib
+     .. code-block:: shell
 
-   Alternatively, copy the required OCI libraries. For example::
+         mkdir ~/lib
+         ln -s ~/instantclient_19_3/libclntsh.dylib ~/lib/
 
-        mkdir ~/lib
-        cp ~/instantclient_19_3/{libclntsh.dylib.19.1,libclntshcore.dylib.19.1,libons.dylib,libnnz12.dylib,libociei.dylib} ~/lib/
+     Instead of linking, you can copy the required OCI libraries. For example:
 
-   For Instant Client 11.2, the OCI libraries must be copied. For example::
+     .. code-block:: shell
 
-        mkdir ~/lib
-        cp ~/instantclient_11_2/{libclntsh.dylib.11.1,libnnz11.dylib,libociei.dylib} ~/lib/
+          mkdir ~/lib
+          cp ~/instantclient_19_3/{libclntsh.dylib.19.1,libclntshcore.dylib.19.1,libnnz19.dylib,libociei.dylib} ~/lib/
+
+     For Instant Client 11.2, the OCI libraries must be copied. For example:
+
+     .. code-block:: shell
+
+          mkdir ~/lib
+          cp ~/instantclient_11_2/{libclntsh.dylib.11.1,libnnz11.dylib,libociei.dylib} ~/lib/
 
 4. If you use optional Oracle configuration files such as ``tnsnames.ora``,
    ``sqlnet.ora`` or ``oraaccess.xml``, put the files in an accessible
    directory. Then set the member
    :member:`dpiContextCreateParams.oracleClientConfigDir` when calling
-   :func:`dpiContext_createWithParams()`, or set the environment variable
-   ``TNS_ADMIN`` to that directory name.
+   :func:`dpiContext_createWithParams()`.
+
+   Alternatively, set the environment variable ``TNS_ADMIN`` to that directory
+   name.
 
    Alternatively, create a ``network/admin`` subdirectory of Instant Client, if
    it does not exist.  For example::

doc/src/releasenotes.rst

@@ -6,6 +6,7 @@ Version 4.0.2 (TBD)
 
 #)  Adjusted check for GNU version of strerror_r() on Cygwin as suggested
     (`issue 138 <https://github.com/oracle/odpi/issues/138>`__).
+#)  Improved documentation.
 
 
 Version 4.0.1 (June 26, 2020)

include/dpi.h

@@ -11,7 +11,7 @@
 
 //-----------------------------------------------------------------------------
 // dpi.h
-//   Master include file for ODPI-C library.
+//   Include file for users of the ODPI-C library.
 //-----------------------------------------------------------------------------
 
 #ifndef DPI_PUBLIC

src/dpiImpl.h

@@ -11,9 +11,9 @@
 
 //-----------------------------------------------------------------------------
 // dpiImpl.h
-//   Master include file for implementation of ODPI-C library. The definitions
-// in this file are subject to change without warning. Only the definitions in
-// the file dpi.h are intended to be used publicly.
+//   Include file for implementation of ODPI-C library. The definitions in this
+// file are subject to change without warning. Only the definitions in the file
+// dpi.h are intended to be used publicly.
 //-----------------------------------------------------------------------------
 
 #ifndef DPI_IMPL

src/dpiSodaDb.c

@@ -197,7 +197,7 @@ int dpiSodaDb_createCollection(dpiSodaDb *db, const char *name,
 //-----------------------------------------------------------------------------
 // dpiSodaDb_createDocument() [PUBLIC]
 //   Create a SODA document that can be inserted in the collection or can be
-// used to replace and existing document in the collection.
+// used to replace an existing document in the collection.
 //-----------------------------------------------------------------------------
 int dpiSodaDb_createDocument(dpiSodaDb *db, const char *key,
         uint32_t keyLength, const char *content, uint32_t contentLength,