Index: /palm/trunk/SOURCE/header.f90
===================================================================
--- /palm/trunk/SOURCE/header.f90	(revision 3551)
+++ /palm/trunk/SOURCE/header.f90	(revision 3552)
@@ -20,5 +20,5 @@
 ! Current revisions:
 ! -----------------
-! 
+! variables documented
 ! 
 ! Former revisions:
@@ -515,70 +515,70 @@
 
     
-    CHARACTER (LEN=2)  ::  do2d_mode           !<
+    CHARACTER (LEN=2)  ::  do2d_mode           !< mode of 2D data output (xy, xz, yz)
     
-    CHARACTER (LEN=5)  ::  section_chr         !<
+    CHARACTER (LEN=5)  ::  section_chr         !< string indicating grid information where to output 2D slices
     
-    CHARACTER (LEN=10) ::  coor_chr            !<
-    CHARACTER (LEN=10) ::  host_chr            !<
+    CHARACTER (LEN=10) ::  coor_chr            !< string for subsidence velocities in large-scale forcing
+    CHARACTER (LEN=10) ::  host_chr            !< string for hostname
     
-    CHARACTER (LEN=16) ::  begin_chr           !<
+    CHARACTER (LEN=16) ::  begin_chr           !< string indication start time for the data output
     
-    CHARACTER (LEN=26) ::  ver_rev             !<
-
-    CHARACTER (LEN=32) ::  cpl_name            !<
+    CHARACTER (LEN=26) ::  ver_rev             !< string for run identification
+
+    CHARACTER (LEN=32) ::  cpl_name            !< name of child domain (nesting mode only) 
     
-    CHARACTER (LEN=40) ::  output_format       !<
+    CHARACTER (LEN=40) ::  output_format       !< netcdf format
     
-    CHARACTER (LEN=70) ::  char1               !<
-    CHARACTER (LEN=70) ::  char2               !<
-    CHARACTER (LEN=70) ::  dopr_chr            !<
-    CHARACTER (LEN=70) ::  do2d_xy             !<
-    CHARACTER (LEN=70) ::  do2d_xz             !<
-    CHARACTER (LEN=70) ::  do2d_yz             !<
-    CHARACTER (LEN=70) ::  do3d_chr            !<
-    CHARACTER (LEN=70) ::  domask_chr          !<
-    CHARACTER (LEN=70) ::  run_classification  !<
+    CHARACTER (LEN=70) ::  char1               !< dummy varialbe used for various strings
+    CHARACTER (LEN=70) ::  char2               !< string containing informating about the advected distance in case of Galilei transformation
+    CHARACTER (LEN=70) ::  dopr_chr            !< string indicating profile output variables
+    CHARACTER (LEN=70) ::  do2d_xy             !< string indicating 2D-xy output variables
+    CHARACTER (LEN=70) ::  do2d_xz             !< string indicating 2D-xz output variables
+    CHARACTER (LEN=70) ::  do2d_yz             !< string indicating 2D-yz output variables
+    CHARACTER (LEN=70) ::  do3d_chr            !< string indicating 3D output variables
+    CHARACTER (LEN=70) ::  domask_chr          !< string indicating masked output variables
+    CHARACTER (LEN=70) ::  run_classification  !< string classifying type of run, e.g. nested, coupled, etc. 
     
-    CHARACTER (LEN=85) ::  r_upper             !<
-    CHARACTER (LEN=85) ::  r_lower             !<
+    CHARACTER (LEN=85) ::  r_upper             !< string indicating model top boundary condition for various quantities
+    CHARACTER (LEN=85) ::  r_lower             !< string indicating bottom boundary condition for various quantities
     
-    CHARACTER (LEN=86) ::  coordinates         !<
-    CHARACTER (LEN=86) ::  gradients           !<
-    CHARACTER (LEN=86) ::  slices              !<
-    CHARACTER (LEN=86) ::  temperatures        !<
-    CHARACTER (LEN=86) ::  ugcomponent         !<
-    CHARACTER (LEN=86) ::  vgcomponent         !<
-
-    CHARACTER (LEN=1), DIMENSION(1:3) ::  dir = (/ 'x', 'y', 'z' /)  !<
-
-    INTEGER(iwp) ::  av             !<
-    INTEGER(iwp) ::  bh             !<
-    INTEGER(iwp) ::  blx            !<
-    INTEGER(iwp) ::  bly            !<
-    INTEGER(iwp) ::  bxl            !<
-    INTEGER(iwp) ::  bxr            !<
-    INTEGER(iwp) ::  byn            !<
-    INTEGER(iwp) ::  bys            !<
-    INTEGER(iwp) ::  ch             !<
-    INTEGER(iwp) ::  count          !<
-    INTEGER(iwp) ::  cpl_parent_id  !<
-    INTEGER(iwp) ::  cwx            !<
-    INTEGER(iwp) ::  cwy            !<
-    INTEGER(iwp) ::  cxl            !<
-    INTEGER(iwp) ::  cxr            !<
-    INTEGER(iwp) ::  cyn            !<
-    INTEGER(iwp) ::  cys            !<
-    INTEGER(iwp) ::  dim            !<
-    INTEGER(iwp) ::  i              !<
-    INTEGER(iwp) ::  io             !<
-    INTEGER(iwp) ::  l              !<
-    INTEGER(iwp) ::  ll             !<
-    INTEGER(iwp) ::  my_cpl_id      !<
-    INTEGER(iwp) ::  n              !<
-    INTEGER(iwp) ::  ncpl           !<
-    INTEGER(iwp) ::  npe_total      !<
+    CHARACTER (LEN=86) ::  coordinates         !< string indicating height coordinates for profile-prescribed variables
+    CHARACTER (LEN=86) ::  gradients           !< string indicating gradients of profile-prescribed variables between the prescribed height coordinates
+    CHARACTER (LEN=86) ::  slices              !< string indicating grid coordinates of profile-prescribed subsidence velocity
+    CHARACTER (LEN=86) ::  temperatures        !< string indicating profile-prescribed subsidence velocities
+    CHARACTER (LEN=86) ::  ugcomponent         !< string indicating profile-prescribed geostrophic u-component
+    CHARACTER (LEN=86) ::  vgcomponent         !< string indicating profile-prescribed geostrophic v-component
+
+    CHARACTER (LEN=1), DIMENSION(1:3) ::  dir = (/ 'x', 'y', 'z' /)  !< string indicating masking steps along certain direction
+
+    INTEGER(iwp) ::  av             !< index indicating average output quantities
+    INTEGER(iwp) ::  bh             !< building height in generic single-building setup
+    INTEGER(iwp) ::  blx            !< building width in grid points along x in generic single-building setup
+    INTEGER(iwp) ::  bly            !< building width in grid points along y in generic single-building setup
+    INTEGER(iwp) ::  bxl            !< index for left building wall in generic single-building setup
+    INTEGER(iwp) ::  bxr            !< index for right building wall in generic single-building setup
+    INTEGER(iwp) ::  byn            !< index for north building wall in generic single-building setup
+    INTEGER(iwp) ::  bys            !< index for south building wall in generic single-building setup
+    INTEGER(iwp) ::  ch             !< canyon depth in generic street-canyon setup
+    INTEGER(iwp) ::  count          !< number of masked output locations
+    INTEGER(iwp) ::  cpl_parent_id  !< parent ID for the respective child model
+    INTEGER(iwp) ::  cwx            !< canyon width along x in generic street-canyon setup
+    INTEGER(iwp) ::  cwy            !< canyon width along y in generic street-canyon setup
+    INTEGER(iwp) ::  cxl            !< index for left canyon wall in generic street-canyon setup
+    INTEGER(iwp) ::  cxr            !< index for right canyon wall in generic street-canyon setup
+    INTEGER(iwp) ::  cyn            !< index for north canyon wall in generic street-canyon setup
+    INTEGER(iwp) ::  cys            !< index for south canyon wall in generic street-canyon setup
+    INTEGER(iwp) ::  dim            !< running index for masking output locations
+    INTEGER(iwp) ::  i              !< running index for various loops
+    INTEGER(iwp) ::  io             !< file unit of HEADER file
+    INTEGER(iwp) ::  l              !< substring length
+    INTEGER(iwp) ::  ll             !< substring length
+    INTEGER(iwp) ::  my_cpl_id      !< run id in a nested model setup
+    INTEGER(iwp) ::  n              !< running index over number of couplers in a nested model setup
+    INTEGER(iwp) ::  ncpl           !< number of coupler in a nested model setup
+    INTEGER(iwp) ::  npe_total      !< number of total PEs in a coupler (parent + child)
     
 
-    REAL(wp) ::  cpuseconds_per_simulated_second  !<
+    REAL(wp) ::  cpuseconds_per_simulated_second  !< CPU time (in s) per simulated second
     REAL(wp) ::  lower_left_coord_x               !< x-coordinate of nest domain
     REAL(wp) ::  lower_left_coord_y               !< y-coordinate of nest domain
Index: /palm/trunk/SOURCE/init_pegrid.f90
===================================================================
--- /palm/trunk/SOURCE/init_pegrid.f90	(revision 3551)
+++ /palm/trunk/SOURCE/init_pegrid.f90	(revision 3552)
@@ -20,5 +20,5 @@
 ! Current revisions:
 ! ------------------
-! 
+! variables documented
 ! 
 ! Former revisions:
@@ -289,42 +289,42 @@
     IMPLICIT NONE
 
-    INTEGER(iwp) ::  i                        !<
-    INTEGER(iwp) ::  id_inflow_l              !<
+    INTEGER(iwp) ::  i                        !< running index over number of processors or number of multigrid level
+    INTEGER(iwp) ::  id_inflow_l              !< ID indicating processors located at the left inflow boundary
     INTEGER(iwp) ::  id_outflow_l             !< local value of id_outflow
     INTEGER(iwp) ::  id_outflow_source_l      !< local value of id_outflow_source
-    INTEGER(iwp) ::  id_recycling_l           !<
+    INTEGER(iwp) ::  id_recycling_l           !< ID indicating processors located at the recycling plane
     INTEGER(iwp) ::  id_stg_left_l            !< left lateral boundary local core id in case of turbulence generator  
     INTEGER(iwp) ::  id_stg_north_l           !< north lateral boundary local core id in case of turbulence generator  
     INTEGER(iwp) ::  id_stg_right_l           !< right lateral boundary local core id in case of turbulence generator  
     INTEGER(iwp) ::  id_stg_south_l           !< south lateral boundary local core id in case of turbulence generator  
-    INTEGER(iwp) ::  ind(5)                   !<
-    INTEGER(iwp) ::  j                        !<
-    INTEGER(iwp) ::  k                        !<
-    INTEGER(iwp) ::  maximum_grid_level_l     !<
-    INTEGER(iwp) ::  mg_levels_x              !<
-    INTEGER(iwp) ::  mg_levels_y              !<
-    INTEGER(iwp) ::  mg_levels_z              !<
-    INTEGER(iwp) ::  mg_switch_to_pe0_level_l !<
-    INTEGER(iwp) ::  nnx_y                    !<
-    INTEGER(iwp) ::  nny_x                    !<
-    INTEGER(iwp) ::  nny_z                    !<
-    INTEGER(iwp) ::  nnz_x                    !<
-    INTEGER(iwp) ::  nnz_y                    !<
-    INTEGER(iwp) ::  numproc_sqr              !<
-    INTEGER(iwp) ::  nxl_l                    !<
-    INTEGER(iwp) ::  nxr_l                    !<
-    INTEGER(iwp) ::  nyn_l                    !<
-    INTEGER(iwp) ::  nys_l                    !<
-    INTEGER(iwp) ::  nzb_l                    !<
-    INTEGER(iwp) ::  nzt_l                    !<
-!$  INTEGER(iwp) ::  omp_get_num_threads      !<
-
-    INTEGER(iwp), DIMENSION(:), ALLOCATABLE ::  ind_all !<
-    INTEGER(iwp), DIMENSION(:), ALLOCATABLE ::  nxlf    !<
-    INTEGER(iwp), DIMENSION(:), ALLOCATABLE ::  nxrf    !<
-    INTEGER(iwp), DIMENSION(:), ALLOCATABLE ::  nynf    !<
-    INTEGER(iwp), DIMENSION(:), ALLOCATABLE ::  nysf    !<
-
-    INTEGER(iwp), DIMENSION(2) ::  pdims_remote         !<
+    INTEGER(iwp) ::  ind(5)                   !< array containing the subdomain bounds
+    INTEGER(iwp) ::  j                        !< running index, used for various loops
+    INTEGER(iwp) ::  k                        !< number of vertical grid points in different multigrid level
+    INTEGER(iwp) ::  maximum_grid_level_l     !< maximum number of grid level without switching to PE 0
+    INTEGER(iwp) ::  mg_levels_x              !< maximum number of grid level allowed along x-direction
+    INTEGER(iwp) ::  mg_levels_y              !< maximum number of grid level allowed along y-direction
+    INTEGER(iwp) ::  mg_levels_z              !< maximum number of grid level allowed along z-direction
+    INTEGER(iwp) ::  mg_switch_to_pe0_level_l !< maximum number of grid level with switching to PE 0
+    INTEGER(iwp) ::  nnx_y                    !< quotient of number of grid points along x-direction and number of PEs used along y-direction
+    INTEGER(iwp) ::  nny_x                    !< quotient of number of grid points along y-direction and number of PEs used along x-direction
+    INTEGER(iwp) ::  nny_z                    !< quotient of number of grid points along y-direction and number of PEs used along x-direction
+    INTEGER(iwp) ::  nnz_x                    !< quotient of number of grid points along z-direction and number of PEs used along x-direction
+    INTEGER(iwp) ::  nnz_y                    !< quotient of number of grid points along z-direction and number of PEs used along x-direction
+    INTEGER(iwp) ::  numproc_sqr              !< square root of the number of processors
+    INTEGER(iwp) ::  nxl_l                    !< lower index bound along x-direction on subdomain and different multigrid level
+    INTEGER(iwp) ::  nxr_l                    !< upper index bound along x-direction on subdomain and different multigrid level
+    INTEGER(iwp) ::  nyn_l                    !< lower index bound along y-direction on subdomain and different multigrid level
+    INTEGER(iwp) ::  nys_l                    !< upper index bound along y-direction on subdomain and different multigrid level
+    INTEGER(iwp) ::  nzb_l                    !< lower index bound along z-direction on subdomain and different multigrid level
+    INTEGER(iwp) ::  nzt_l                    !< upper index bound along z-direction on subdomain and different multigrid level
+!$  INTEGER(iwp) ::  omp_get_num_threads      !< number of OpenMP threads
+
+    INTEGER(iwp), DIMENSION(:), ALLOCATABLE ::  ind_all !< dummy array containing index bounds on subdomain, used for gathering
+    INTEGER(iwp), DIMENSION(:), ALLOCATABLE ::  nxlf    !< lower index bound allong x-direction for every PE
+    INTEGER(iwp), DIMENSION(:), ALLOCATABLE ::  nxrf    !< upper index bound allong x-direction for every PE
+    INTEGER(iwp), DIMENSION(:), ALLOCATABLE ::  nynf    !< lower index bound allong y-direction for every PE
+    INTEGER(iwp), DIMENSION(:), ALLOCATABLE ::  nysf    !< lower index bound allong y-direction for every PE
+
+    INTEGER(iwp), DIMENSION(2) ::  pdims_remote         !< number of PEs used for coupled model (only in atmospher-ocean coupling)
     INTEGER(iwp)               ::  lcoord(2)            !< PE coordinates of left neighbor along x and y
     INTEGER(iwp)               ::  rcoord(2)            !< PE coordinates of right neighbor along x and y
Index: /palm/trunk/SOURCE/netcdf_data_input_mod.f90
===================================================================
--- /palm/trunk/SOURCE/netcdf_data_input_mod.f90	(revision 3551)
+++ /palm/trunk/SOURCE/netcdf_data_input_mod.f90	(revision 3552)
@@ -20,5 +20,5 @@
 ! Current revisions:
 ! -----------------
-! 
+! variables documented and unused variables removed
 ! 
 ! Former revisions:
@@ -306,6 +306,5 @@
        INTEGER(iwp) ::  tind_p !< time index for following time in mesoscale-offline nesting
 
-       LOGICAL      ::  init         = .FALSE.
-       LOGICAL      ::  from_file    = .FALSE.
+       LOGICAL      ::  init         = .FALSE. !< flag indicating that offline nesting is already initialized
 
        REAL(wp), DIMENSION(:), ALLOCATABLE ::  surface_pressure !< time dependent surface pressure
@@ -1171,5 +1170,5 @@
        INTEGER(iwp) ::  val      !< value of the attribute
        
-       LOGICAL ::  global                 !< flag indicating a global or a variable's attribute
+       LOGICAL ::  global        !< flag indicating a global or a variable's attribute
 
 #if defined ( __netcdf )
@@ -3135,5 +3134,5 @@
        IMPLICIT NONE
 
-       CHARACTER(LEN=100), DIMENSION(:), ALLOCATABLE ::  var_names
+       CHARACTER(LEN=100), DIMENSION(:), ALLOCATABLE ::  var_names !< string containing all variables on file
       
        INTEGER(iwp) ::  id_dynamic !< NetCDF id of dynamic input file
@@ -3281,6 +3280,4 @@
        INTEGER(iwp) ::  num_vars   !< number of variables in netcdf input file
        INTEGER(iwp) ::  t          !< running index time dimension
-
-       nest_offl%from_file = MERGE( .TRUE., .FALSE., input_pids_dynamic ) 
 !
 !--    Skip input if no forcing from larger-scale models is applied.
@@ -5030,5 +5027,5 @@
        INTEGER(iwp)                ::  id_var           !< dimension id
 
-       REAL(wp), DIMENSION(:), INTENT(INOUT) ::  var  !< variable to be read
+       REAL(wp), DIMENSION(:), INTENT(INOUT) ::  var    !< variable to be read
 #if defined( __netcdf )
 
@@ -5395,5 +5392,5 @@
                                                          !< to its reverse memory access
 
-       REAL(wp), DIMENSION(:,:,:), INTENT(INOUT) ::  var  !< variable to be read
+       REAL(wp), DIMENSION(:,:,:), INTENT(INOUT) ::  var !< variable to be read
 #if defined( __netcdf )
 
@@ -5874,7 +5871,7 @@
        IMPLICIT NONE
 
-       CHARACTER(LEN=6) ::  message_identifier
-       CHARACTER(LEN=*) ::  routine_name
-       CHARACTER(LEN=*), OPTIONAL ::  name
+       CHARACTER(LEN=6) ::  message_identifier !< string for the error number
+       CHARACTER(LEN=*) ::  routine_name       !< routine name where the error happened
+       CHARACTER(LEN=*), OPTIONAL ::  name     !< name of variable where reading failed
 
        INTEGER(iwp) ::  errno
Index: /palm/trunk/SOURCE/sum_up_3d_data.f90
===================================================================
--- /palm/trunk/SOURCE/sum_up_3d_data.f90	(revision 3551)
+++ /palm/trunk/SOURCE/sum_up_3d_data.f90	(revision 3552)
@@ -20,5 +20,5 @@
 ! Current revisions:
 ! -----------------
-! 
+! variables documented
 ! 
 ! Former revisions:
@@ -309,10 +309,10 @@
     INTEGER(iwp) ::  j   !< grid index y direction
     INTEGER(iwp) ::  k   !< grid index x direction
-    INTEGER(iwp) ::  m   !< running index surface type
-    INTEGER(iwp) ::  n   !< 
-
-    REAL(wp)     ::  mean_r !< 
-    REAL(wp)     ::  s_r2   !< 
-    REAL(wp)     ::  s_r3   !< 
+    INTEGER(iwp) ::  m   !< running index over surfacle elements
+    INTEGER(iwp) ::  n   !< running index over number of particles per grid box
+
+    REAL(wp)     ::  mean_r !< mean-particle radius witin grid box
+    REAL(wp)     ::  s_r2   !< mean-particle radius witin grid box to the power of two
+    REAL(wp)     ::  s_r3   !< mean-particle radius witin grid box to the power of three
 
     CHARACTER (LEN=varnamelength) ::  trimvar  !< TRIM of output-variable string
