DOC: Add docstrings

src/CaosDB.jl

@@ -26,9 +26,12 @@ module CaosDB
 module Info
 
 """
-Struct containing version information of the CaosDB server.
+Struct containing version information of the CaosDB server. Meant
+mainly for internal usage; use `CaosDB.Connection.get_version_info` or
+`CaosDB.Connection.print_version_info` to retrieve the version of the
+connected CaosDB server.
 """
-mutable struct VersionInfo
+mutable struct _VersionInfo
 
     major::Cint
     minor::Cint
@@ -36,7 +39,7 @@ mutable struct VersionInfo
     pre_release::Cstring
     build::Cstring
 
-    VersionInfo() = new()
+    _VersionInfo() = new()
 
 end
 
@@ -70,12 +73,15 @@ end # Utility
 module Authentication
 
 """
-Struct containing a pointer to the wrapped cpp authenticator class.
+Struct containing a pointer to the wrapped cpp authenticator
+class. Meant for internal use; call a
+`CaosDB.Authentication.create_<authenticator>` function to create an
+authenticator object from a configuration.
 """
-mutable struct Authenticator
+mutable struct _Authenticator
     wrapped_authenticator::Ptr{Cvoid}
 
-    function Authenticator()
+    function _Authenticator()
         auth = new()
         # force this to point to C_NULL after initialization
         auth.wrapped_authenticator = C_NULL
@@ -85,8 +91,8 @@ mutable struct Authenticator
                 ccall(
                     (:caosdb_authentication_delete_authenticator, "libccaosdb"),
                     Cint,
-                    (Ref{Authenticator},),
-                    Ref{Authenticator}(t),
+                    (Ref{_Authenticator},),
+                    Ref{_Authenticator}(t),
                 )
             end
         end
@@ -94,17 +100,27 @@ mutable struct Authenticator
     end
 end
 
+"""
+    create_plain_password_authenticator(
+        username::AbstractString,
+        password::AbstractString,
+    )
+
+Return an authenticator object that contains a wrapped cpp
+plain-password authenticator configured with `username` and
+`password`.
+"""
 function create_plain_password_authenticator(
     username::AbstractString,
     password::AbstractString,
 )
 
-    auth = Ref{Authenticator}(Authenticator())
+    auth = Ref{_Authenticator}(_Authenticator())
 
     err_code = ccall(
         (:caosdb_authentication_create_plain_password_authenticator, "libccaosdb"),
         Cint,
-        (Ref{Authenticator}, Cstring, Cstring),
+        (Ref{_Authenticator}, Cstring, Cstring),
         auth,
         username,
         password,
@@ -126,13 +142,17 @@ module Connection
 
 using ..CaosDB
 
+export connect
+
 """
-Struct containing the actual connection to a CaosDB server.
+Struct containing the actual connection to a CaosDB server. Meant for
+internal use; call a `CaosDB.Connection.create_<connection>` function
+to create an connection object from a configuration.
 """
-mutable struct CaosDBConnection
+mutable struct _Connection
     wrapped_connection::Ptr{Cvoid}
 
-    function CaosDBConnection()
+    function _Connection()
         conn = new()
         conn.wrapped_connection = C_NULL
         function f(t)
@@ -140,8 +160,8 @@ mutable struct CaosDBConnection
                 ccall(
                     (:caosdb_connection_delete_connection, "libccaosdb"),
                     Cint,
-                    (Ref{CaosDBConnection},),
-                    Ref{CaosDBConnection}(t),
+                    (Ref{_Connection},),
+                    Ref{_Connection}(t),
                 )
             end
         end
@@ -151,12 +171,14 @@ end
 
 """
 Struct containing a pointer to the wrapped cpp class providing the
-certificate provider.
+certificate provider. Meant for internal use; call a
+`CaosDB.Connection.create_<certificate_provider>` function to create
+an certificate-provider object from a configuration.
 """
-mutable struct CertificateProvider
+mutable struct _CertificateProvider
     wrapped_certificate_provider::Ptr{Cvoid}
 
-    function CertificateProvider()
+    function _CertificateProvider()
         prov = new()
         prov.wrapped_certificate_provider = C_NULL
         function f(t)
@@ -164,8 +186,8 @@ mutable struct CertificateProvider
                 ccall(
                     (:caosdb_connection_delete_certificate_provider, "libccaosdb"),
                     Cint,
-                    (Ref{CertificateProvider},),
-                    Ref{CertificateProvider}(t),
+                    (Ref{_CertificateProvider},),
+                    Ref{_CertificateProvider}(t),
                 )
             end
         end
@@ -175,12 +197,14 @@ end
 
 """
 Struct containing a pointer to the wrapped cpp class for storing the
-connection configuration.
+connection configuration. Meant for internal use; call a
+`CaosDB.Connection.create_<configuration>` function to create
+an connection-configuration object from a configuration.
 """
-mutable struct Configuration
+mutable struct _Configuration
     wrapped_connection_configuration::Ptr{Cvoid}
 
-    function Configuration()
+    function _Configuration()
         config = new()
         config.wrapped_connection_configuration = C_NULL
         function f(t)
@@ -188,8 +212,8 @@ mutable struct Configuration
                 ccall(
                     (:caosdb_connection_delete_connection_configuration, "libcaosdb"),
                     Cint,
-                    (Ref{Configuration},),
-                    Ref{Configuration}(t),
+                    (Ref{_Configuration},),
+                    Ref{_Configuration}(t),
                 )
             end
         end
@@ -200,17 +224,17 @@ end
 """
     create_pem_file_certificate_provider(path::AbstractString)
 
-Return a `CertificateProvider` for the pem certificate located at
+Return a `_CertificateProvider` for the pem certificate located at
 `path`.
 """
 function create_pem_file_certificate_provider(path::AbstractString)
 
-    cert_provider = Ref{CertificateProvider}(CertificateProvider())
+    cert_provider = Ref{_CertificateProvider}(_CertificateProvider())
 
     err_code = ccall(
         (:caosdb_connection_create_pem_file_certificate_provider, "libccaosdb"),
         Cint,
-        (Ref{CertificateProvider}, Cstring),
+        (Ref{_CertificateProvider}, Cstring),
         cert_provider,
         path,
     )
@@ -229,8 +253,8 @@ end
     create_tls_connection_configuration(
         host::AbstractString,
         port::Cint,
-        authenticator::Ref{CaosDB.Authentication.Authenticator},
-        provider::Ref{CertificateProvider}
+        authenticator::Ref{CaosDB.Authentication._Authenticator},
+        provider::Ref{_CertificateProvider}
         )
 
 Return a TLS connection configuration with authentication.
@@ -238,21 +262,21 @@ Return a TLS connection configuration with authentication.
 function create_tls_connection_configuration(
     host::AbstractString,
     port::Cint,
-    authenticator::Ref{CaosDB.Authentication.Authenticator},
-    provider::Ref{CertificateProvider},
+    authenticator::Ref{CaosDB.Authentication._Authenticator},
+    provider::Ref{_CertificateProvider},
 )
 
-    config = Ref{Configuration}(Configuration())
+    config = Ref{_Configuration}(_Configuration())
 
     err_code = ccall(
         (:caosdb_connection_create_tls_connection_configuration, "libccaosdb"),
         Cint,
         (
-            Ref{Configuration},
+            Ref{_Configuration},
             Cstring,
             Cint,
-            Ref{CaosDB.Authentication.Authenticator},
-            Ref{CertificateProvider},
+            Ref{CaosDB.Authentication._Authenticator},
+            Ref{_CertificateProvider},
         ),
         config,
         host,
@@ -273,12 +297,12 @@ end
 
 function create_insecure_connection_configuration(host::AbstractString, port::Cint)
 
-    config = Ref{Configuration}(Configuration())
+    config = Ref{_Configuration}(_Configuration())
 
     err_code = ccall(
         (:caosdb_connection_create_insecure_connection_configuration, "libccaosdb"),
         Cint,
-        (Ref{Configuration}, Cstring, Cint),
+        (Ref{_Configuration}, Cstring, Cint),
         config,
         host,
         port,
@@ -294,18 +318,18 @@ function create_insecure_connection_configuration(host::AbstractString, port::Ci
 end
 
 """
-    create_connection(config::Ref{Configuration})
+    create_connection(config::Ref{_Configuration})
 
 Return a connection based on the given `config`.
 """
-function create_connection(config::Ref{Configuration})
+function create_connection(config::Ref{_Configuration})
 
-    connection = Ref{CaosDBConnection}(CaosDBConnection())
+    connection = Ref{_Connection}(_Connection())
 
     err_code = ccall(
         (:caosdb_connection_create_connection, "libccaosdb"),
         Cint,
-        (Ref{CaosDBConnection}, Ref{Configuration}),
+        (Ref{_Connection}, Ref{_Configuration}),
         connection,
         config,
     )
@@ -321,19 +345,19 @@ function create_connection(config::Ref{Configuration})
 end
 
 """
-    get_version_info(con::Ref{CaosDBConnection})
+    get_version_info(con::Ref{_Connection})
 
 Return the version of the CaosDB server that `con` is connected
 to.
 """
-function get_version_info(con::Ref{CaosDBConnection})
+function get_version_info(con::Ref{_Connection})
 
-    info = Ref{CaosDB.Info.VersionInfo}(CaosDB.Info.VersionInfo())
+    info = Ref{CaosDB.Info._VersionInfo}(CaosDB.Info._VersionInfo())
 
     err_code = ccall(
         (:caosdb_connection_get_version_info, "libccaosdb"),
         Cint,
-        (Ref{CaosDB.Info.VersionInfo}, Ref{CaosDBConnection}),
+        (Ref{CaosDB.Info._VersionInfo}, Ref{_Connection}),
         info,
         con,
     )
@@ -350,12 +374,12 @@ function get_version_info(con::Ref{CaosDBConnection})
 end
 
 """
-    print_version_info(con::Ref{CaosDBConnection})
+    print_version_info(con::Ref{_Connection})
 
 Retrieve the version info for the CaosDB server `con` is connected to,
 and print the version in a nice message.
 """
-function print_version_info(con::Ref{CaosDBConnection})
+function print_version_info(con::Ref{_Connection})
 
     # Dereference to access the fields
     info = get_version_info(con)[]
@@ -372,41 +396,87 @@ function print_version_info(con::Ref{CaosDBConnection})
 
 end
 
-function connect(
-    host::AbstractString = nothing,
-    port_str::AbstractString = nothing,
-    cacert::AbstractString = nothing,
-    username::AbstractString = nothing,
-    password::AbstractString = nothing,
+"""
+    function connect([;
+        host::AbstractString="",
+        port_str::AbstractString="undefined",
+        cacert::AbstractString="",
+        username::AbstractString="",
+        password::AbstractString="undefined"]
     )
 
-    if host == nothing
+Return a connection object created for the given `host`:`port` with an
+SSL certificate located at `cacert` with the given credentials.
+
+# Extended help
+
+!!! info
+
+    Because of type-stability, and since an empty string may be a
+    valid password, the value of `password`, for which it is fetched
+    from an environmental variable, is "undefined". This means that if
+    you absolutely must use "undefined" as your password, you have to
+    specify it via the `CAOSDB_PASSWORD` variable.
+
+# Arguments
+- `host::AbstractString=""`: The hostname of the CaosDB server. If
+  none is provided, the `CAOSDB_SERVER_HOST` environmental variable is
+  used instead. If that's not defined, "localhost" is used.
+- `port_str::AbstractString="undefined"`: The port of the CaosDB
+  server, given as string. If none is provided, the
+  `CAOSDB_SERVER_GRPC_PORT_HTTPS` environmental variable is used
+  instead. If that's not defined, "8443" is used. The default value is
+  "undefined" rather than an empty string because an empty string
+  could be a valid port, too, i.e. the CaosDB server is available at
+  `host` without a port.
+- `cacert::AbstractString=""`: The path to the SSL certificate of the
+  CaosDB server. If none is provided, the `CAOSDB_SERVER_CERT`
+  environmental variable is used instead.
+- `username::AbstractString=""`: The username with which to log in
+  into the CaosDB server. If none is provided, the `CAOSDB_USER`
+  environmental variable is used instead. If that's not defined,
+  "admin" is used.
+- `password::AbstractString="undefined"`: The password with which to
+  log in into the CaosDB server. If none is provided, the
+  `CAOSDB_PASSWORD` environmental variable is used instead. If that's
+  not defined, "caosdb" is used. The default value is "undefined"
+  rather than an empty string to allow an empty password.
+"""
+function connect(;
+    host::AbstractString="",
+    port_str::AbstractString="undefined",
+    cacert::AbstractString="",
+    username::AbstractString="",
+    password::AbstractString="undefined"
+)
+
+    if host == ""
 
         host = CaosDB.Utility.get_env_var("CAOSDB_SERVER_HOST", "localhost")
 
     end
 
-    if port_str == nothing
+    if port_str == "undefined"
 
-        port = CaosDB.Utility.get_env_var("CAOSDB_SERVER_GRPC_PORT_HTTPS", "8443")
+        port_str = CaosDB.Utility.get_env_var("CAOSDB_SERVER_GRPC_PORT_HTTPS", "8443")
 
     end
 
     port = parse(Cint, port_str)
 
-    if cacert == nothing
+    if cacert == ""
 
         cacert = CaosDB.Utility.get_env_var("CAOSDB_SERVER_CERT")
 
     end
 
-    if username == nothing
+    if username == ""
 
         username = CaosDB.Utility.get_env_var("CAOSDB_USER", "admin")
 
     end
 
-    if password == nothing
+    if password == "undefined"
 
         password = CaosDB.Utility.get_env_var("CAOSDB_PASSWORD", "caosdb")
 
@@ -423,8 +493,6 @@ function connect(
 
 end
 
-export connect
-
 end # Connection
 
 module Entity end