Index: palm/trunk/SOURCE/land_surface_model.f90
===================================================================
--- palm/trunk/SOURCE/land_surface_model.f90	(revision 1591)
+++ palm/trunk/SOURCE/land_surface_model.f90	(revision 1682)
@@ -1,4 +1,3 @@
- MODULE land_surface_model_mod
-
+!> @file land_surface_model.f90
 !--------------------------------------------------------------------------------!
 ! This file is part of PALM.
@@ -20,5 +19,5 @@
 ! Current revisions:
 ! -----------------
-! 
+! Code annotations made doxygen readable 
 ! 
 ! Former revisions:
@@ -65,24 +64,22 @@
 ! Description:
 ! ------------
-! Land surface model, consisting of a solver for the energy balance at the
-! surface and a four layer soil scheme. The scheme is similar to the TESSEL
-! scheme implemented in the ECMWF IFS model, with modifications according to
-! H-TESSEL. The implementation is based on the formulation implemented in the 
-! DALES and UCLA-LES models.
-!
-! To do list:
-! -----------
-! - Check dewfall parametrization for fog simulations
-! - Consider partial absorption of the net shortwave radiation by the surface layer
-! - Allow for water surfaces, check performance for bare soils 
-! - Invert indices (running from -3 to 0. Currently: nzb_soil=0, nzt_soil=3))
-! - Implement surface runoff model (required when performing long-term LES with
-!   considerable precipitation
-!
-! Notes:
-! ------
-! - No time step criterion is required as long as the soil layers do not become
-!   too thin
+!> Land surface model, consisting of a solver for the energy balance at the
+!> surface and a four layer soil scheme. The scheme is similar to the TESSEL
+!> scheme implemented in the ECMWF IFS model, with modifications according to
+!> H-TESSEL. The implementation is based on the formulation implemented in the 
+!> DALES and UCLA-LES models.
+!>
+!> @todo Check dewfall parametrization for fog simulations.
+!> @todo Consider partial absorption of the net shortwave radiation by the surface layer.
+!> @todo Allow for water surfaces, check performance for bare soils.
+!> @todo Invert indices (running from -3 to 0. Currently: nzb_soil=0, nzt_soil=3)).
+!> @todo Implement surface runoff model (required when performing long-term LES with
+!>       considerable precipitation.
+!>
+!> @note  No time step criterion is required as long as the soil layers do not become
+!>        too thin.
 !------------------------------------------------------------------------------!
+ MODULE land_surface_model_mod
+ 
      USE arrays_3d,                                                            &
          ONLY:  pt, pt_p, q_p, qsws, rif, shf, ts, us, z0, z0h
@@ -116,9 +113,9 @@
 !
 !-- LSM model constants
-    INTEGER(iwp), PARAMETER :: nzb_soil = 0, & !: bottom of the soil model (to be switched)
-                               nzt_soil = 3, & !: top of the soil model (to be switched)
-                               nzs = 4         !: number of soil layers (fixed for now)
-
-    INTEGER(iwp) :: dots_soil = 0  !: starting index for timeseries output 
+    INTEGER(iwp), PARAMETER :: nzb_soil = 0, & !< bottom of the soil model (to be switched)
+                               nzt_soil = 3, & !< top of the soil model (to be switched)
+                               nzs = 4         !< number of soil layers (fixed for now)
+
+    INTEGER(iwp) :: dots_soil = 0  !< starting index for timeseries output 
 
     INTEGER(iwp), DIMENSION(0:1) :: id_dim_zs_xy, id_dim_zs_xz, id_dim_zs_yz,  &
@@ -141,63 +138,63 @@
 !
 !-- LSM variables
-    INTEGER(iwp) :: veg_type  = 2, & !: vegetation type, 0: user-defined, 1-19: generic (see list)
-                    soil_type = 3    !: soil type, 0: user-defined, 1-6: generic (see list)
-
-    LOGICAL :: conserve_water_content = .TRUE., & !: open or closed bottom surface for the soil model
-               dewfall = .TRUE.,                & !: allow/inhibit dewfall
-               land_surface = .FALSE.             !: flag parameter indicating wheather the lsm is used
+    INTEGER(iwp) :: veg_type  = 2, & !< vegetation type, 0: user-defined, 1-19: generic (see list)
+                    soil_type = 3    !< soil type, 0: user-defined, 1-6: generic (see list)
+
+    LOGICAL :: conserve_water_content = .TRUE., & !< open or closed bottom surface for the soil model
+               dewfall = .TRUE.,                & !< allow/inhibit dewfall
+               land_surface = .FALSE.             !< flag parameter indicating wheather the lsm is used
 
 !   value 9999999.9_wp -> generic available or user-defined value must be set
 !   otherwise -> no generic variable and user setting is optional
-    REAL(wp) :: alpha_vangenuchten = 9999999.9_wp,      & !: NAMELIST alpha_vg
-                canopy_resistance_coefficient = 9999999.9_wp, & !: NAMELIST g_d
-                c_surface   = 20000.0_wp,               & !: Surface (skin) heat capacity
-                drho_l_lv,                              & !: (rho_l * l_v)**-1
-                exn,                                    & !: value of the Exner function
-                e_s = 0.0_wp,                           & !: saturation water vapour pressure
-                field_capacity = 9999999.9_wp,          & !: NAMELIST m_fc
-                f_shortwave_incoming = 9999999.9_wp,    & !: NAMELIST f_sw_in
-                hydraulic_conductivity = 9999999.9_wp,  & !: NAMELIST gamma_w_sat
-                ke = 0.0_wp,                            & !: Kersten number
-                lambda_surface_stable = 9999999.9_wp,   & !: NAMELIST lambda_surface_s
-                lambda_surface_unstable = 9999999.9_wp, & !: NAMELIST lambda_surface_u
-                leaf_area_index = 9999999.9_wp,         & !: NAMELIST lai
-                l_vangenuchten = 9999999.9_wp,          & !: NAMELIST l_vg
-                min_canopy_resistance = 9999999.9_wp,   & !: NAMELIST r_canopy_min
-                min_soil_resistance = 50.0_wp,          & !: NAMELIST r_soil_min
-                m_total = 0.0_wp,                       & !: weighted total water content of the soil (m3/m3)
-                n_vangenuchten = 9999999.9_wp,          & !: NAMELIST n_vg
-                q_s = 0.0_wp,                           & !: saturation specific humidity
-                residual_moisture = 9999999.9_wp,       & !: NAMELIST m_res
-                rho_cp,                                 & !: rho_surface * cp
-                rho_lv,                                 & !: rho * l_v
-                rd_d_rv,                                & !: r_d / r_v
-                saturation_moisture = 9999999.9_wp,     & !: NAMELIST m_sat
-                vegetation_coverage = 9999999.9_wp,     & !: NAMELIST c_veg
-                wilting_point = 9999999.9_wp,           & !: NAMELIST m_wilt
-                z0_eb  = 9999999.9_wp,                  & !: NAMELIST z0 (lsm_par)
-                z0h_eb = 9999999.9_wp                    !: NAMELIST z0h (lsm_par)
+    REAL(wp) :: alpha_vangenuchten = 9999999.9_wp,      & !< NAMELIST alpha_vg
+                canopy_resistance_coefficient = 9999999.9_wp, & !< NAMELIST g_d
+                c_surface   = 20000.0_wp,               & !< Surface (skin) heat capacity
+                drho_l_lv,                              & !< (rho_l * l_v)**-1
+                exn,                                    & !< value of the Exner function
+                e_s = 0.0_wp,                           & !< saturation water vapour pressure
+                field_capacity = 9999999.9_wp,          & !< NAMELIST m_fc
+                f_shortwave_incoming = 9999999.9_wp,    & !< NAMELIST f_sw_in
+                hydraulic_conductivity = 9999999.9_wp,  & !< NAMELIST gamma_w_sat
+                ke = 0.0_wp,                            & !< Kersten number
+                lambda_surface_stable = 9999999.9_wp,   & !< NAMELIST lambda_surface_s
+                lambda_surface_unstable = 9999999.9_wp, & !< NAMELIST lambda_surface_u
+                leaf_area_index = 9999999.9_wp,         & !< NAMELIST lai
+                l_vangenuchten = 9999999.9_wp,          & !< NAMELIST l_vg
+                min_canopy_resistance = 9999999.9_wp,   & !< NAMELIST r_canopy_min
+                min_soil_resistance = 50.0_wp,          & !< NAMELIST r_soil_min
+                m_total = 0.0_wp,                       & !< weighted total water content of the soil (m3/m3)
+                n_vangenuchten = 9999999.9_wp,          & !< NAMELIST n_vg
+                q_s = 0.0_wp,                           & !< saturation specific humidity
+                residual_moisture = 9999999.9_wp,       & !< NAMELIST m_res
+                rho_cp,                                 & !< rho_surface * cp
+                rho_lv,                                 & !< rho * l_v
+                rd_d_rv,                                & !< r_d / r_v
+                saturation_moisture = 9999999.9_wp,     & !< NAMELIST m_sat
+                vegetation_coverage = 9999999.9_wp,     & !< NAMELIST c_veg
+                wilting_point = 9999999.9_wp,           & !< NAMELIST m_wilt
+                z0_eb  = 9999999.9_wp,                  & !< NAMELIST z0 (lsm_par)
+                z0h_eb = 9999999.9_wp                    !< NAMELIST z0h (lsm_par)
 
     REAL(wp), DIMENSION(nzb_soil:nzt_soil) :: &
-              ddz_soil,                     & !: 1/dz_soil
-              ddz_soil_stag,                & !: 1/dz_soil_stag
-              dz_soil,                      & !: soil grid spacing (center-center)
-              dz_soil_stag,                 & !: soil grid spacing (edge-edge) 
-              root_extr = 0.0_wp,           & !: root extraction
+              ddz_soil,                     & !< 1/dz_soil
+              ddz_soil_stag,                & !< 1/dz_soil_stag
+              dz_soil,                      & !< soil grid spacing (center-center)
+              dz_soil_stag,                 & !< soil grid spacing (edge-edge) 
+              root_extr = 0.0_wp,           & !< root extraction
               root_fraction = (/9999999.9_wp, 9999999.9_wp,    &
-                                9999999.9_wp, 9999999.9_wp /), & !: distribution of root surface area to the individual soil layers
-              zs = (/0.07_wp, 0.28_wp, 1.00_wp,  2.89_wp/),    & !: soil layer depths (m)
-              soil_moisture = 0.0_wp          !: soil moisture content (m3/m3)
+                                9999999.9_wp, 9999999.9_wp /), & !< distribution of root surface area to the individual soil layers
+              zs = (/0.07_wp, 0.28_wp, 1.00_wp,  2.89_wp/),    & !< soil layer depths (m)
+              soil_moisture = 0.0_wp          !< soil moisture content (m3/m3)
 
     REAL(wp), DIMENSION(nzb_soil:nzt_soil+1) ::   &
               soil_temperature = (/290.0_wp, 287.0_wp, 285.0_wp,  283.0_wp,    &
-                                   283.0_wp /) !: soil temperature (K)
+                                   283.0_wp /) !< soil temperature (K)
 
 #if defined( __nopointer )
-    REAL(wp), DIMENSION(:,:), ALLOCATABLE, TARGET :: t_surface,   & !: surface temperature (K)
-                                                     t_surface_p, & !: progn. surface temperature (K)
-                                                     m_liq_eb,    & !: liquid water reservoir (m)
-                                                     m_liq_eb_av, & !: liquid water reservoir (m)
-                                                     m_liq_eb_p     !: progn. liquid water reservoir (m)
+    REAL(wp), DIMENSION(:,:), ALLOCATABLE, TARGET :: t_surface,   & !< surface temperature (K)
+                                                     t_surface_p, & !< progn. surface temperature (K)
+                                                     m_liq_eb,    & !< liquid water reservoir (m)
+                                                     m_liq_eb_av, & !< liquid water reservoir (m)
+                                                     m_liq_eb_p     !< progn. liquid water reservoir (m)
 #else
     REAL(wp), DIMENSION(:,:), POINTER :: t_surface,      &
@@ -213,66 +210,66 @@
 !
 !-- Temporal tendencies for time stepping            
-    REAL(wp), DIMENSION(:,:), ALLOCATABLE :: tt_surface_m,  & !: surface temperature tendency (K)
-                                             tm_liq_eb_m      !: liquid water reservoir tendency (m)
+    REAL(wp), DIMENSION(:,:), ALLOCATABLE :: tt_surface_m,  & !< surface temperature tendency (K)
+                                             tm_liq_eb_m      !< liquid water reservoir tendency (m)
 
 !
 !-- Energy balance variables                
     REAL(wp), DIMENSION(:,:), ALLOCATABLE ::                                   &
-              alpha_vg,         & !: coef. of Van Genuchten
-              c_liq,            & !: liquid water coverage (of vegetated area)
-              c_liq_av,         & !: average of c_liq
-              c_soil_av,        & !: average of c_soil
-              c_veg,            & !: vegetation coverage
-              c_veg_av,         & !: average of c_veg
-              f_sw_in,          & !: fraction of absorbed shortwave radiation by the surface layer (not implemented yet)
-              ghf_eb,           & !: ground heat flux
-              ghf_eb_av,        & !: average of ghf_eb
-              gamma_w_sat,      & !: hydraulic conductivity at saturation
-              g_d,              & !: coefficient for dependence of r_canopy on water vapour pressure deficit
-              lai,              & !: leaf area index
-              lai_av,           & !: average of lai
-              lambda_h_sat,     & !: heat conductivity for dry soil
-              lambda_surface_s,    & !: coupling between surface and soil (depends on vegetation type)
-              lambda_surface_u,    & !: coupling between surface and soil (depends on vegetation type)
-              l_vg,             & !: coef. of Van Genuchten
-              m_fc,             & !: soil moisture at field capacity (m3/m3)
-              m_res,            & !: residual soil moisture
-              m_sat,            & !: saturation soil moisture (m3/m3)
-              m_wilt,           & !: soil moisture at permanent wilting point (m3/m3)
-              n_vg,             & !: coef. Van Genuchten  
-              qsws_eb,          & !: surface flux of latent heat (total)
-              qsws_eb_av,       & !: average of qsws_eb
-              qsws_liq_eb,      & !: surface flux of latent heat (liquid water portion)
-              qsws_liq_eb_av,   & !: average of qsws_liq_eb
-              qsws_soil_eb,     & !: surface flux of latent heat (soil portion)
-              qsws_soil_eb_av,  & !: average of qsws_soil_eb
-              qsws_veg_eb,      & !: surface flux of latent heat (vegetation portion)
-              qsws_veg_eb_av,   & !: average of qsws_veg_eb
-              rad_net_l,        & !: local copy of rad_net (net radiation at surface)
-              r_a,              & !: aerodynamic resistance 
-              r_a_av,           & !: avergae of r_a
-              r_canopy,         & !: canopy resistance
-              r_soil,           & !: soil resitance
-              r_soil_min,       & !: minimum soil resistance
-              r_s,              & !: total surface resistance (combination of r_soil and r_canopy)
-              r_s_av,           & !: avergae of r_s
-              r_canopy_min,     & !: minimum canopy (stomatal) resistance
-              shf_eb,           & !: surface flux of sensible heat
-              shf_eb_av           !: average of shf_eb
+              alpha_vg,         & !< coef. of Van Genuchten
+              c_liq,            & !< liquid water coverage (of vegetated area)
+              c_liq_av,         & !< average of c_liq
+              c_soil_av,        & !< average of c_soil
+              c_veg,            & !< vegetation coverage
+              c_veg_av,         & !< average of c_veg
+              f_sw_in,          & !< fraction of absorbed shortwave radiation by the surface layer (not implemented yet)
+              ghf_eb,           & !< ground heat flux
+              ghf_eb_av,        & !< average of ghf_eb
+              gamma_w_sat,      & !< hydraulic conductivity at saturation
+              g_d,              & !< coefficient for dependence of r_canopy on water vapour pressure deficit
+              lai,              & !< leaf area index
+              lai_av,           & !< average of lai
+              lambda_h_sat,     & !< heat conductivity for dry soil
+              lambda_surface_s,    & !< coupling between surface and soil (depends on vegetation type)
+              lambda_surface_u,    & !< coupling between surface and soil (depends on vegetation type)
+              l_vg,             & !< coef. of Van Genuchten
+              m_fc,             & !< soil moisture at field capacity (m3/m3)
+              m_res,            & !< residual soil moisture
+              m_sat,            & !< saturation soil moisture (m3/m3)
+              m_wilt,           & !< soil moisture at permanent wilting point (m3/m3)
+              n_vg,             & !< coef. Van Genuchten  
+              qsws_eb,          & !< surface flux of latent heat (total)
+              qsws_eb_av,       & !< average of qsws_eb
+              qsws_liq_eb,      & !< surface flux of latent heat (liquid water portion)
+              qsws_liq_eb_av,   & !< average of qsws_liq_eb
+              qsws_soil_eb,     & !< surface flux of latent heat (soil portion)
+              qsws_soil_eb_av,  & !< average of qsws_soil_eb
+              qsws_veg_eb,      & !< surface flux of latent heat (vegetation portion)
+              qsws_veg_eb_av,   & !< average of qsws_veg_eb
+              rad_net_l,        & !< local copy of rad_net (net radiation at surface)
+              r_a,              & !< aerodynamic resistance 
+              r_a_av,           & !< avergae of r_a
+              r_canopy,         & !< canopy resistance
+              r_soil,           & !< soil resitance
+              r_soil_min,       & !< minimum soil resistance
+              r_s,              & !< total surface resistance (combination of r_soil and r_canopy)
+              r_s_av,           & !< avergae of r_s
+              r_canopy_min,     & !< minimum canopy (stomatal) resistance
+              shf_eb,           & !< surface flux of sensible heat
+              shf_eb_av           !< average of shf_eb
 
     REAL(wp), DIMENSION(:,:,:), ALLOCATABLE ::                                 &
-              lambda_h, &   !: heat conductivity of soil (?)                            
-              lambda_w, &   !: hydraulic diffusivity of soil (?)
-              gamma_w,  &   !: hydraulic conductivity of soil (?)
-              rho_c_total   !: volumetric heat capacity of the actual soil matrix (?) 
+              lambda_h, &   !< heat conductivity of soil (?)                            
+              lambda_w, &   !< hydraulic diffusivity of soil (?)
+              gamma_w,  &   !< hydraulic conductivity of soil (?)
+              rho_c_total   !< volumetric heat capacity of the actual soil matrix (?) 
 
 #if defined( __nopointer )
     REAL(wp), DIMENSION(:,:,:), ALLOCATABLE, TARGET ::                         &
-              t_soil,    & !: Soil temperature (K)
-              t_soil_av, & !: Average of t_soil
-              t_soil_p,  & !: Prog. soil temperature (K)
-              m_soil,    & !: Soil moisture (m3/m3)
-              m_soil_av, & !: Average of m_soil
-              m_soil_p     !: Prog. soil moisture (m3/m3)
+              t_soil,    & !< Soil temperature (K)
+              t_soil_av, & !< Average of t_soil
+              t_soil_p,  & !< Prog. soil temperature (K)
+              m_soil,    & !< Soil moisture (m3/m3)
+              m_soil_av, & !< Average of m_soil
+              m_soil_p     !< Prog. soil moisture (m3/m3)
 #else
     REAL(wp), DIMENSION(:,:,:), POINTER ::                                     &
@@ -287,7 +284,7 @@
 
     REAL(wp), DIMENSION(:,:,:), ALLOCATABLE ::                                 &
-              tt_soil_m, & !: t_soil storage array 
-              tm_soil_m, & !: m_soil storage array 
-              root_fr      !: root fraction (sum=1) 
+              tt_soil_m, & !< t_soil storage array 
+              tm_soil_m, & !< m_soil storage array 
+              root_fr      !< root fraction (sum=1) 
 
 
@@ -518,5 +515,5 @@
 ! Description:
 ! ------------
-!-- Allocate land surface model arrays and define pointers
+!> Allocate land surface model arrays and define pointers
 !------------------------------------------------------------------------------!
     SUBROUTINE init_lsm_arrays
@@ -601,5 +598,5 @@
 ! Description:
 ! ------------
-!-- Initialization of the land surface model
+!> Initialization of the land surface model
 !------------------------------------------------------------------------------!
     SUBROUTINE init_lsm
@@ -608,7 +605,7 @@
        IMPLICIT NONE
 
-       INTEGER(iwp) ::  i !: running index
-       INTEGER(iwp) ::  j !: running index
-       INTEGER(iwp) ::  k !: running index
+       INTEGER(iwp) ::  i !< running index
+       INTEGER(iwp) ::  j !< running index
+       INTEGER(iwp) ::  k !< running index
 
 
@@ -920,11 +917,10 @@
 ! Description:
 ! ------------
-! Solver for the energy balance at the surface.
-!
-! Note: surface fluxes are calculated in the land surface model, but these are
-! not used in the atmospheric code. The fluxes are calculated afterwards in
-! prandtl_fluxes using the surface values of temperature and humidity as
-! provided by the land surface model. In this way, the fluxes in the land
-! surface model are not equal to the ones calculated in prandtl_fluxes
+!> Solver for the energy balance at the surface.
+!> @note Surface fluxes are calculated in the land surface model, but these are
+!>       not used in the atmospheric code. The fluxes are calculated afterwards in
+!>       prandtl_fluxes using the surface values of temperature and humidity as
+!>       provided by the land surface model. In this way, the fluxes in the land
+!>       surface model are not equal to the ones calculated in prandtl_fluxes
 !------------------------------------------------------------------------------!
     SUBROUTINE lsm_energy_balance
@@ -933,27 +929,27 @@
        IMPLICIT NONE
 
-       INTEGER(iwp) ::  i         !: running index
-       INTEGER(iwp) ::  j         !: running index
-       INTEGER(iwp) ::  k, ks     !: running index
-
-       REAL(wp) :: f1,          & !: resistance correction term 1
-                   f2,          & !: resistance correction term 2
-                   f3,          & !: resistance correction term 3
-                   m_min,       & !: minimum soil moisture
-                   T_1,         & !: actual temperature at first grid point
-                   e,           & !: water vapour pressure
-                   e_s,         & !: water vapour saturation pressure
-                   e_s_dt,      & !: derivate of e_s with respect to T
-                   tend,        & !: tendency
-                   dq_s_dt,     & !: derivate of q_s with respect to T
-                   coef_1,      & !: coef. for prognostic equation
-                   coef_2,      & !: coef. for prognostic equation
-                   f_qsws,      & !: factor for qsws_eb
-                   f_qsws_veg,  & !: factor for qsws_veg_eb
-                   f_qsws_soil, & !: factor for qsws_soil_eb
-                   f_qsws_liq,  & !: factor for qsws_liq_eb
-                   f_shf,       & !: factor for shf_eb
-                   lambda_surface, & !: Current value of lambda_surface
-                   m_liq_eb_max   !: maxmimum value of the liq. water reservoir
+       INTEGER(iwp) ::  i         !< running index
+       INTEGER(iwp) ::  j         !< running index
+       INTEGER(iwp) ::  k, ks     !< running index
+
+       REAL(wp) :: f1,          & !< resistance correction term 1
+                   f2,          & !< resistance correction term 2
+                   f3,          & !< resistance correction term 3
+                   m_min,       & !< minimum soil moisture
+                   T_1,         & !< actual temperature at first grid point
+                   e,           & !< water vapour pressure
+                   e_s,         & !< water vapour saturation pressure
+                   e_s_dt,      & !< derivate of e_s with respect to T
+                   tend,        & !< tendency
+                   dq_s_dt,     & !< derivate of q_s with respect to T
+                   coef_1,      & !< coef. for prognostic equation
+                   coef_2,      & !< coef. for prognostic equation
+                   f_qsws,      & !< factor for qsws_eb
+                   f_qsws_veg,  & !< factor for qsws_veg_eb
+                   f_qsws_soil, & !< factor for qsws_soil_eb
+                   f_qsws_liq,  & !< factor for qsws_liq_eb
+                   f_shf,       & !< factor for shf_eb
+                   lambda_surface, & !< Current value of lambda_surface
+                   m_liq_eb_max   !< maxmimum value of the liq. water reservoir
 
 
@@ -1308,7 +1304,6 @@
 ! Description:
 ! ------------
-!
-! Soil model as part of the land surface model. The model predicts soil
-! temperature and water content.
+!> Soil model as part of the land surface model. The model predicts soil
+!> temperature and water content.
 !------------------------------------------------------------------------------!
     SUBROUTINE lsm_soil_model
@@ -1317,13 +1312,13 @@
        IMPLICIT NONE
 
-       INTEGER(iwp) ::  i   !: running index
-       INTEGER(iwp) ::  j   !: running index
-       INTEGER(iwp) ::  k   !: running index
-
-       REAL(wp)     :: h_vg !: Van Genuchten coef. h
-
-       REAL(wp), DIMENSION(nzb_soil:nzt_soil) :: gamma_temp,  & !: temp. gamma
-                                               lambda_temp, & !: temp. lambda
-                                               tend           !: tendency
+       INTEGER(iwp) ::  i   !< running index
+       INTEGER(iwp) ::  j   !< running index
+       INTEGER(iwp) ::  k   !< running index
+
+       REAL(wp)     :: h_vg !< Van Genuchten coef. h
+
+       REAL(wp), DIMENSION(nzb_soil:nzt_soil) :: gamma_temp,  & !< temp. gamma
+                                               lambda_temp, & !< temp. lambda
+                                               tend           !< tendency
 
        DO i = nxlg, nxrg    
@@ -1564,5 +1559,5 @@
 ! Description:
 ! ------------
-! Calculation of specific humidity of the surface layer (surface)
+!> Calculation of specific humidity of the surface layer (surface)
 !------------------------------------------------------------------------------!
     SUBROUTINE calc_q_surface
@@ -1570,8 +1565,8 @@
        IMPLICIT NONE
 
-       INTEGER :: i              !: running index
-       INTEGER :: j              !: running index
-       INTEGER :: k              !: running index
-       REAL(wp) :: resistance    !: aerodynamic and soil resistance term
+       INTEGER :: i              !< running index
+       INTEGER :: j              !< running index
+       INTEGER :: k              !< running index
+       REAL(wp) :: resistance    !< aerodynamic and soil resistance term
 
        DO i = nxlg, nxrg    
@@ -1605,5 +1600,5 @@
 ! Description:
 ! ------------
-! Swapping of timelevels
+!> Swapping of timelevels
 !------------------------------------------------------------------------------!
     SUBROUTINE lsm_swap_timelevel ( mod_count )
