docs(model): fix docstrings for base model/pkg types (#1490)

src/Model/BaseModel.f90

@@ -1,5 +1,3 @@
-!Highest level model class.  All models inherit from this parent class.
-
 module BaseModelModule
 
   use KindModule, only: DP, I4B
@@ -11,9 +9,9 @@ module BaseModelModule
   public :: BaseModelType, CastAsBaseModelClass, AddBaseModelToList, &
             GetBaseModelFromList
 
+  !> @brief Highest level model type. All models extend this parent type.
   type :: BaseModelType
     character(len=LENMEMPATH) :: memoryPath !< the location in the memory manager where the variables are stored
-
     character(len=LENMODELNAME), pointer :: name => null() !< name of the model
     character(len=3), pointer :: macronym => null() !< 3 letter model acronym (GWF, GWT, ...)
     integer(I4B), pointer :: idsoln => null() !< id of the solution model is in
@@ -37,90 +35,45 @@ module BaseModelModule
 
 contains
 
+  !> @brief Define the model
+  !<
   subroutine model_df(this)
-! ******************************************************************************
-! modeldf -- Define the model
-! ******************************************************************************
-!
-!    SPECIFICATIONS:
-! ------------------------------------------------------------------------------
     class(BaseModelType) :: this
-! ------------------------------------------------------------------------------
-    !
-    ! -- return
-    return
   end subroutine model_df
 
+  !> @brief Allocate and read
+  !<
   subroutine model_ar(this)
-! ******************************************************************************
-! modelar -- Allocate and read
-! ******************************************************************************
-!
-!    SPECIFICATIONS:
-! ------------------------------------------------------------------------------
     class(BaseModelType) :: this
-! ------------------------------------------------------------------------------
-    !
-    ! -- return
-    return
   end subroutine model_ar
 
+  !> @brief Read and prepare
+  !<
   subroutine model_rp(this)
-! ******************************************************************************
-! model_rp -- Read and prepare
-! ******************************************************************************
-!
-!    SPECIFICATIONS:
-! ------------------------------------------------------------------------------
     class(BaseModelType) :: this
-! ------------------------------------------------------------------------------
-    !
-    ! -- return
-    return
   end subroutine model_rp
 
+  !> @brief Calculate time step length
+  !<
   subroutine model_calculate_delt(this)
-! ******************************************************************************
-! model_calculate_delt -- Calculate time step length
-! ******************************************************************************
-!
-!    SPECIFICATIONS:
-! ------------------------------------------------------------------------------
     class(BaseModelType) :: this
-! ------------------------------------------------------------------------------
-    !
-    ! -- return
-    return
   end subroutine model_calculate_delt
 
+  !> @brief Output results
+  !<
   subroutine model_ot(this)
-! ******************************************************************************
-! model_ot -- output results
-! ******************************************************************************
-!
-!    SPECIFICATIONS:
-! ------------------------------------------------------------------------------
     class(BaseModelType) :: this
-! ------------------------------------------------------------------------------
-    !
-    ! -- return
-    return
   end subroutine model_ot
 
+  !> @brief Write line to model iout
+  !<
   subroutine model_message(this, line, fmt)
-! ******************************************************************************
-! model_message -- write line to model iout
-! ******************************************************************************
-!
-!    SPECIFICATIONS:
-! ------------------------------------------------------------------------------
     ! -- dummy
     class(BaseModelType) :: this
     character(len=*), intent(in) :: line
     character(len=*), intent(in), optional :: fmt
     ! -- local
     character(len=LINELENGTH) :: cfmt
-! ------------------------------------------------------------------------------
     !
     ! -- process optional variables
     if (present(fmt)) then
@@ -131,38 +84,22 @@ subroutine model_message(this, line, fmt)
     !
     ! -- write line
     write (this%iout, trim(cfmt)) trim(line)
-    !
-    ! -- return
-    return
   end subroutine model_message
 
+  !> @brief Final processing
+  !<
   subroutine model_fp(this)
-! ******************************************************************************
-! model_fp -- Final processing
-! ******************************************************************************
-!
-!    SPECIFICATIONS:
-! ------------------------------------------------------------------------------
     class(BaseModelType) :: this
-! ------------------------------------------------------------------------------
-    !
-    ! -- return
-    return
   end subroutine model_fp
 
+  !> @brief Allocate scalar variables
+  !<
   subroutine allocate_scalars(this, modelname)
-! ******************************************************************************
-! allocate_scalars
-! ******************************************************************************
-!
-!    SPECIFICATIONS:
-! ------------------------------------------------------------------------------
     ! -- modules
     use MemoryManagerModule, only: mem_allocate
     ! -- dummy
     class(BaseModelType) :: this
     character(len=*), intent(in) :: modelname
-! ------------------------------------------------------------------------------
     !
     call mem_allocate(this%name, LENMODELNAME, 'NAME', this%memoryPath)
     call mem_allocate(this%macronym, 3, 'MACRONYM', this%memoryPath)
@@ -183,23 +120,15 @@ subroutine allocate_scalars(this, modelname)
     this%iprflow = 0
     this%ipakcb = 0
     this%inewton = 0 !default is standard formulation
-    !
-    ! -- return
-    return
   end subroutine allocate_scalars
 
+  !> @brief Deallocate
+  !<
   subroutine model_da(this)
-! ******************************************************************************
-! deallocate
-! ******************************************************************************
-!
-!    SPECIFICATIONS:
-! ------------------------------------------------------------------------------
     ! -- modules
     use MemoryManagerModule, only: mem_deallocate
     ! -- dummy
     class(BaseModelType) :: this
-! ------------------------------------------------------------------------------
     !
     ! -- Strings
     call mem_deallocate(this%name, 'NAME', this%memoryPath)
@@ -213,13 +142,9 @@ subroutine model_da(this)
     call mem_deallocate(this%iprflow)
     call mem_deallocate(this%ipakcb)
     call mem_deallocate(this%idsoln)
-    !
-    ! -- return
-    return
   end subroutine model_da
 
   function CastAsBaseModelClass(obj) result(res)
-    implicit none
     class(*), pointer, intent(inout) :: obj
     class(BaseModelType), pointer :: res
     !
@@ -230,11 +155,9 @@ function CastAsBaseModelClass(obj) result(res)
     class is (BaseModelType)
       res => obj
     end select
-    return
   end function CastAsBaseModelClass
 
   subroutine AddBaseModelToList(list, model)
-    implicit none
     ! -- dummy
     type(ListType), intent(inout) :: list
     class(BaseModelType), pointer, intent(inout) :: model
@@ -243,12 +166,9 @@ subroutine AddBaseModelToList(list, model)
     !
     obj => model
     call list%Add(obj)
-    !
-    return
   end subroutine AddBaseModelToList
 
   function GetBaseModelFromList(list, idx) result(res)
-    implicit none
     ! -- dummy
     type(ListType), intent(inout) :: list
     integer(I4B), intent(in) :: idx
@@ -258,8 +178,6 @@ function GetBaseModelFromList(list, idx) result(res)
     !
     obj => list%GetItem(idx)
     res => CastAsBaseModelClass(obj)
-    !
-    return
   end function GetBaseModelFromList
 
 end module BaseModelModule

src/Model/ExplicitModel.f90

@@ -21,12 +21,7 @@ module ExplicitModelModule
             AddExplicitModelToList, &
             GetExplicitModelFromList
 
-  !> @brief Derived type for the Explicit Model Type
-  !!
-  !! This derived type describes a parent class for explicit
-  !! models.
-  !!
-  !<
+  !> @brief Base type for explicit models.
   type, extends(BaseModelType) :: ExplicitModelType
     type(ListType), pointer :: bndlist => null() !< array of boundary packages for this model
     class(DisBaseType), pointer :: dis => null() !< discretization object
@@ -45,18 +40,12 @@ module ExplicitModelModule
   !<
   subroutine model_ad(this)
     class(ExplicitModelType) :: this
-    !
-    ! -- return
-    return
   end subroutine model_ad
 
   !> @ brief Solve the model
   !<
   subroutine model_solve(this)
     class(ExplicitModelType) :: this
-    !
-    ! -- return
-    return
   end subroutine model_solve
 
   !> @ brief Calculate model flows
@@ -65,9 +54,6 @@ subroutine model_cq(this, icnvg, isuppress_output)
     class(ExplicitModelType) :: this
     integer(I4B), intent(in) :: icnvg
     integer(I4B), intent(in) :: isuppress_output
-    !
-    ! -- return
-    return
   end subroutine model_cq
 
   !> @ brief Calculate model budget
@@ -76,9 +62,6 @@ subroutine model_bd(this, icnvg, isuppress_output)
     class(ExplicitModelType) :: this
     integer(I4B), intent(in) :: icnvg
     integer(I4B), intent(in) :: isuppress_output
-    !
-    ! -- return
-    return
   end subroutine model_bd
 
   !> @ brief Deallocate the model
@@ -87,22 +70,13 @@ subroutine model_da(this)
     ! -- modules
     use MemoryManagerModule, only: mem_deallocate
     class(ExplicitModelType) :: this
-
-    ! -- Scalars
-    !
-    ! -- Arrays
     !
     ! -- derived types
     call this%bndlist%Clear()
     deallocate (this%bndlist)
     !
-    ! -- nullify pointers
-    !
     ! -- BaseModelType
     call this%BaseModelType%model_da()
-    !
-    ! -- Return
-    return
   end subroutine model_da
 
   !> @ brief Allocate model scalar variables
@@ -117,11 +91,6 @@ subroutine allocate_scalars(this, modelname)
     !
     ! -- allocate members from this type
     allocate (this%bndlist)
-    !
-    ! -- initialize
-    !
-    ! -- return
-    return
   end subroutine allocate_scalars
 
   !> @ brief Cast a generic object into an explicit model
@@ -137,7 +106,6 @@ function CastAsExplicitModelClass(obj) result(res)
     class is (ExplicitModelType)
       res => obj
     end select
-    return
   end function CastAsExplicitModelClass
 
   !> @ brief Add explicit model to a generic list
@@ -151,8 +119,6 @@ subroutine AddExplicitModelToList(list, model)
     !
     obj => model
     call list%Add(obj)
-    !
-    return
   end subroutine AddExplicitModelToList
 
   !> @ brief Get generic object from list and return as explicit model
@@ -167,8 +133,6 @@ function GetExplicitModelFromList(list, idx) result(res)
     !
     obj => list%GetItem(idx)
     res => CastAsExplicitModelClass(obj)
-    !
-    return
   end function GetExplicitModelFromList
 
 end module ExplicitModelModule