Minor updates.

app/dmbeat.f90

@@ -44,7 +44,7 @@ program dmbeat
     ! Initialise DMPACK.
     call dm_init()
 
-    ! Read command-line options and configuration from file.
+    ! Read command-line options and configuration file.
     rc = read_args(app)
     if (dm_is_error(rc)) call dm_stop(STOP_FAILURE)
 

app/dmbot.f90

@@ -63,7 +63,7 @@ program dmbot
         rc = dm_jabber_create(jabber)
 
         if (dm_is_error(rc)) then
-            call dm_error_out(rc)
+            call logger%error('failed to create libstrophe context', error=rc)
             exit init_block
         end if
 
@@ -81,16 +81,16 @@ program dmbot
                                tls_trusted  = APP_TLS_TRUSTED)
 
         if (dm_is_error(rc)) then
-            call dm_error_out(rc)
+            call logger%error('failed to connect to ' // trim(app%host) // ':' // &
+                              dm_itoa(app%port), error=rc)
             exit init_block
         end if
 
-        call logger%info('started ' // APP_NAME)
-
         ! Register signal handler.
         call dm_signal_register(signal_callback)
 
         ! Run event loop of bot.
+        call logger%info('started ' // APP_NAME)
         call dm_jabber_run(jabber)
     end block init_block
 
@@ -240,15 +240,11 @@ subroutine connect_callback(connection, event, error, stream_error, user_data) b
 
         if (event == XMPP_CONN_CONNECT) then
             call logger%debug('connected')
-
             call xmpp_handler_add(connection, message_callback, '', 'message', '', c_null_ptr)
-
             call dm_jabber_send_presence(jabber, JABBER_STANZA_TEXT_ONLINE)
         else
             call logger%debug('disconnected')
-
             call xmpp_handler_delete(connection, message_callback)
-
             call xmpp_stop(jabber%ctx)
         end if
     end subroutine connect_callback

app/dmsync.f90

@@ -54,7 +54,7 @@ program dmsync
     ! Initialise DMPACK.
     call dm_init()
 
-    ! Read command-line options and configuration from file.
+    ! Read command-line options and configuration file.
     rc = read_args(app)
     if (dm_is_error(rc)) call dm_stop(STOP_FAILURE)
 

src/dm_jabber.f90

@@ -30,8 +30,8 @@ module dm_jabber
     !! call dm_jabber_shutdown()
     !! ```
     !!
-    !! The connection callback must be of C-interoperable abstract interface
-    !! `dm_jabber_connection_handler()`, which is an alias for
+    !! The callback passed to the connect function must be of C-interoperable
+    !! abstract interface `dm_jabber_connect_callback()`, which is an alias for
     !! `xmpp_conn_handler()` from module `xmpp`, for example:
     !!
     !! ```fortran
@@ -69,7 +69,7 @@ module dm_jabber
     use, intrinsic :: iso_c_binding
     use :: xmpp, dm_jabber_callback              => xmpp_handler,              &
                  dm_jabber_certfail_callback     => xmpp_certfail_handler,     &
-                 dm_jabber_connect_callback   => xmpp_conn_handler,         &
+                 dm_jabber_connect_callback      => xmpp_conn_handler,         &
                  dm_jabber_global_timed_callback => xmpp_global_timed_handler, &
                  dm_jabber_log_callback          => xmpp_log_handler,          &
                  dm_jabber_password_callback     => xmpp_password_callback,    &
@@ -252,9 +252,8 @@ integer function dm_jabber_connect(jabber, host, port, jid, password, callback,
         if (present(tls_trusted))  tls_trusted_  = tls_trusted
 
         ! Create new connection.
-        jabber%connection = xmpp_conn_new(jabber%ctx)
-
         rc = E_XMPP
+        jabber%connection = xmpp_conn_new(jabber%ctx)
         if (.not. c_associated(jabber%connection)) return
 
         ! Set flags.
@@ -338,7 +337,8 @@ integer function dm_jabber_create(jabber, log_level) result(rc)
     end function dm_jabber_create
 
     integer function dm_jabber_disconnect(jabber) result(rc)
-        !! Disconnects from server and releases connection.
+        !! Disconnects from server and releases connection. The function returns
+        !! `E_XMPP` on error.
         type(jabber_type), intent(inout) :: jabber !! Jabber context type.
 
         integer :: stat
@@ -395,7 +395,7 @@ subroutine dm_jabber_send_presence(jabber, show, status)
 
         type(jabber_type), intent(inout)        :: jabber !! Jabber context type.
         character(len=*),  intent(in), optional :: show   !! Availability (`online`, `offline`, `dnd`, …).
-        character(len=*),  intent(in), optional :: status !! Status description text.
+        character(len=*),  intent(in), optional :: status !! Human-readable status description text.
 
         integer     :: stat
         type(c_ptr) :: attr, pres, text