Index: palm/trunk/UTIL/inifor/src/inifor_control.f90
===================================================================
--- palm/trunk/UTIL/inifor/src/inifor_control.f90	(revision 3447)
+++ palm/trunk/UTIL/inifor/src/inifor_control.f90	(revision 3557)
@@ -26,4 +26,8 @@
 ! -----------------
 ! $Id$
+! Updated documentation
+! 
+! 
+! 3447 2018-10-29 15:52:54Z eckhard
 ! Renamed source files for compatibilty with PALM build system
 !
@@ -44,5 +48,5 @@
 ! Authors:
 ! --------
-! @author Eckhard Kadasch
+!> @author Eckhard Kadasch (Deutscher Wetterdienst, Offenbach)
 !
 ! Description:
@@ -61,19 +65,31 @@
     IMPLICIT NONE
 
-    CHARACTER (LEN=5000) ::  message = ''
+    CHARACTER (LEN=5000) ::  message = '' !< log message buffer
 
  CONTAINS
 
+!------------------------------------------------------------------------------!
+! Description:
+! ------------
+!> 
+!> report() is INIFOR's general logging routine. It prints the given 'message'
+!> to the terminal and writes it to the INIFOR log file.
+!> 
+!> You can use this routine to log events across INIFOR's code to log. For
+!> warnings and abort messages, you may use the dedicated routines warn() and
+!> abort() in this module. Both use report() and add specific behaviour to it.
+!------------------------------------------------------------------------------!
     SUBROUTINE report(routine, message, debug)
 
-       CHARACTER(LEN=*), INTENT(IN)  ::  routine
-       CHARACTER(LEN=*), INTENT(IN)  ::  message
-       LOGICAL, OPTIONAL, INTENT(IN) ::  debug
-       INTEGER                       ::  u
-       LOGICAL, SAVE                 ::  is_first_run = .TRUE.
-       LOGICAL                       ::  suppress_message
-
-
-       IF (is_first_run)  THEN
+       CHARACTER(LEN=*), INTENT(IN)  ::  routine !< name of calling subroutine of function
+       CHARACTER(LEN=*), INTENT(IN)  ::  message !< log message
+       LOGICAL, OPTIONAL, INTENT(IN) ::  debug   !< flag the current message as debugging message
+
+       INTEGER                       ::  u                     !< Fortran file unit for the log file
+       LOGICAL, SAVE                 ::  is_first_run = .TRUE. !< control flag for file opening mode
+       LOGICAL                       ::  suppress_message      !< control falg for additional debugging log
+
+
+       IF ( is_first_run )  THEN
           OPEN( NEWUNIT=u, FILE='inifor.log', STATUS='replace' )
           is_first_run = .FALSE.
@@ -84,9 +100,9 @@
 
        suppress_message = .FALSE.
-       IF (PRESENT(debug))  THEN
-          IF (.NOT. debug)  suppress_message = .TRUE.
+       IF ( PRESENT(debug) )  THEN
+          IF ( .NOT. debug )  suppress_message = .TRUE.
        END IF
 
-       IF (.NOT. suppress_message)  THEN
+       IF ( .NOT. suppress_message )  THEN
           PRINT *, "inifor: " // TRIM(message) // "  [ " // TRIM(routine) // " ]"
           WRITE(u, *)  TRIM(message) // "  [ " // TRIM(routine) // " ]"
@@ -98,8 +114,18 @@
 
 
+!------------------------------------------------------------------------------!
+! Description:
+! ------------
+!> 
+!> warn() prepends "WARNING:" the given 'message' and prints the result to the
+!> terminal and writes it to the INIFOR logfile.
+!> 
+!> You can use this routine for messaging issues, that still allow INIFOR to
+!> continue.
+!------------------------------------------------------------------------------!
     SUBROUTINE warn(routine, message)
 
-       CHARACTER(LEN=*), INTENT(IN) ::  routine
-       CHARACTER(LEN=*), INTENT(IN) ::  message
+       CHARACTER(LEN=*), INTENT(IN) ::  routine !< name of calling subroutine or function
+       CHARACTER(LEN=*), INTENT(IN) ::  message !< log message
 
        CALL report(routine, "WARNING: " // TRIM(message))
@@ -108,8 +134,18 @@
 
 
+!------------------------------------------------------------------------------!
+! Description:
+! ------------
+!> 
+!> abort() prepends "ERROR:" the given 'message' and prints the result to the
+!> terminal, writes it to the INIFOR logfile, and exits INIFOR.
+!> 
+!> You can use this routine for messaging issues, that are critical and prevent
+!> INIFOR from continueing.
+!------------------------------------------------------------------------------!
     SUBROUTINE abort(routine, message)
 
-       CHARACTER(LEN=*), INTENT(IN) ::  routine
-       CHARACTER(LEN=*), INTENT(IN) ::  message
+       CHARACTER(LEN=*), INTENT(IN) ::  routine !< name of calling subroutine or function
+       CHARACTER(LEN=*), INTENT(IN) ::  message !< log message
 
        CALL report(routine, "ERROR: " // TRIM(message) // " Stopping.")
@@ -119,4 +155,10 @@
 
 
+!------------------------------------------------------------------------------!
+! Description:
+! ------------
+!> 
+!> print_version() prints the INIFOR version number and copyright notice.
+!------------------------------------------------------------------------------!
     SUBROUTINE print_version()
        PRINT *, "INIFOR " // VERSION
@@ -125,15 +167,26 @@
 
 
+!------------------------------------------------------------------------------!
+! Description:
+! ------------
+!> 
+!> run_control() measures the run times of various parts of INIFOR and
+!> accumulates them in timing budgets.
+!------------------------------------------------------------------------------!
     SUBROUTINE run_control(mode, budget)
 
-       CHARACTER(LEN=*), INTENT(IN) ::  mode, budget
-       REAL(dp), SAVE               ::  t0, t1
-       REAL(dp), SAVE               ::  t_comp=0.0_dp, &
-                                        t_alloc=0.0_dp, &
-                                        t_init=0.0_dp, &
-                                        t_read=0.0_dp, &
-                                        t_total=0.0_dp, &
-                                        t_write=0.0_dp
-       CHARACTER(LEN=*), PARAMETER  ::  fmt='(F6.2)'
+       CHARACTER(LEN=*), INTENT(IN) ::  mode   !< name of the calling mode
+       CHARACTER(LEN=*), INTENT(IN) ::  budget !< name of the timing budget
+
+       REAL(dp), SAVE ::  t0               !< begin of timing interval
+       REAL(dp), SAVE ::  t1               !< end of timing interval
+       REAL(dp), SAVE ::  t_comp  = 0.0_dp !< computation timing budget
+       REAL(dp), SAVE ::  t_alloc = 0.0_dp !< allocation timing budget
+       REAL(dp), SAVE ::  t_init  = 0.0_dp !< initialization timing budget
+       REAL(dp), SAVE ::  t_read  = 0.0_dp !< reading timing budget
+       REAL(dp), SAVE ::  t_total = 0.0_dp !< total time
+       REAL(dp), SAVE ::  t_write = 0.0_dp !< writing timing budget
+
+       CHARACTER(LEN=*), PARAMETER  ::  fmt='(F6.2)' !< floating-point output format
 
 
