add comment blocks at the start of each subroutine

[martynpclark]

Need to describe the purpose of the subroutine, the method, and references where appropriate

[bartnijssen]

Will start working on this now, following the coding guidelines that we established. This will require review from @martynpclark when I make the pull request.

[bartnijssen]

Done. The comment blocks are simple. The coding conventions document has been updated accordingly with the following:

Include a comment block at the start of each subroutine or function, providing a brief description of what the subroutine does (including references). To indicate that this is the start of a subroutine or function, the comment should start with ! <scope> subroutine <subroutine name>: <description> or ! <scope> function <function name>: <description>, where <scope> is private|public|internal. The line above and after this one lines has the form ! *****. For example:

     ! ************************************************************************************************
     ! public subroutine init_metad: initialize metadata structures
     ! ************************************************************************************************

If there is a more detailed description (which is encouraged), then continue with comments after the above header and end with another line of the form `! *****`, for example:

     ! ************************************************************************************************
     ! public subroutine groundwatr: compute the groundwater sink term in Richards' equation
     ! ************************************************************************************************
     !
     ! Method
     ! ------
     !
     ! Here we assume that water avaialble for shallow groundwater flow includes is all water above
     ! "field capacity" below the depth zCrit, where zCrit is defined as the lowest point in the soil
     ! profile where the volumetric liquid water content is less than field capacity.
     !
     ! We further assume that transmssivity (m2 s-1) for each layer is defined asuming that the water
     ! available for saturated flow is located at the bottom of the soil profile. Specifically:
     !  trTotal(iLayer) = tran0*(zActive(iLayer)/soilDepth)**zScale_TOPMODEL
     !  trSoil(iLayer)  = trTotal(iLayer) - trTotal(iLayer+1)
     ! where zActive(iLayer) is the effective water table thickness for all layers up to and including
     ! the current layer (working from the bottom to the top).
     !
     ! The outflow from each layer is then (m3 s-1)
     !  mLayerOutflow(iLayer) = trSoil(iLayer)*tan_slope*contourLength
     ! where contourLength is the width of a hillslope (m) parallel to a stream
     !
     ! ************************************************************************************************