From 94eca0de2b96dacaa09602000d76cdaaeb69a9c8 Mon Sep 17 00:00:00 2001 From: wpbonelli Date: Fri, 8 Dec 2023 10:05:24 -0500 Subject: [PATCH] docs(model): fix docstrings for base model/pkg types --- src/Model/BaseModel.f90 | 120 ++++++--------------------------- src/Model/ExplicitModel.f90 | 38 +---------- src/Model/NumericalPackage.f90 | 55 ++++++--------- 3 files changed, 40 insertions(+), 173 deletions(-) diff --git a/src/Model/BaseModel.f90 b/src/Model/BaseModel.f90 index 29a71992fd2..d33b2541b8f 100644 --- a/src/Model/BaseModel.f90 +++ b/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 diff --git a/src/Model/ExplicitModel.f90 b/src/Model/ExplicitModel.f90 index ae5630b83da..a2b0f98b920 100644 --- a/src/Model/ExplicitModel.f90 +++ b/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 diff --git a/src/Model/NumericalPackage.f90 b/src/Model/NumericalPackage.f90 index 1d9e66decf0..ee9c81fd048 100644 --- a/src/Model/NumericalPackage.f90 +++ b/src/Model/NumericalPackage.f90 @@ -60,11 +60,11 @@ module NumericalPackageModule contains ! !> @ brief Set package names - !! - !! Method to assign the filtyp (ftype), the model name, and package name for - !! a package. This method also creates the memoryPath and memoryPathModel that - !! is used by the memory manager when variables are allocated. - !! + !! + !! Method to assign the filtyp (ftype), the model name, and package name for + !! a package. This method also creates the memoryPath and memoryPathModel that + !! is used by the memory manager when variables are allocated. + !! !< subroutine set_names(this, ibcnum, name_model, pakname, ftype, input_mempath) ! -- dummy variables @@ -95,15 +95,12 @@ subroutine set_names(this, ibcnum, name_model, pakname, ftype, input_mempath) end if this%memoryPath = create_mem_path(name_model, this%packName) this%memoryPathModel = create_mem_path(name_model) - ! - ! -- return - return end subroutine set_names !> @ brief Allocate package scalars - !! - !! Allocate and initialize base numerical package scalars. - !! + !! + !! Allocate and initialize base numerical package scalars. + !! !< subroutine allocate_scalars(this) ! -- modules @@ -166,15 +163,12 @@ subroutine allocate_scalars(this) call mem_set_value(this%input_fname, 'INPUT_FNAME', & this%input_mempath, found) end if - ! - ! -- return - return end subroutine allocate_scalars !> @ brief Deallocate package scalars - !! - !! Deallocate and initialize base numerical package scalars. - !! + !! + !! Deallocate and initialize base numerical package scalars. + !! !< subroutine da(this) ! -- modules @@ -195,18 +189,15 @@ subroutine da(this) call mem_deallocate(this%ipakcb) call mem_deallocate(this%ionper) call mem_deallocate(this%lastonper) - ! - ! -- return - return end subroutine da !> @ brief Check ionper - !! - !! Generic method to read and check ionperiod, which is used to determine - !! if new period data should be read from the input file. The check of - !! ionperiod also makes sure periods are increasing in subsequent period - !! data blocks. - !! + !! + !! Generic method to read and check ionperiod, which is used to determine + !! if new period data should be read from the input file. The check of + !! ionperiod also makes sure periods are increasing in subsequent period + !! data blocks. + !! !< subroutine read_check_ionper(this) ! -- modules @@ -227,15 +218,12 @@ subroutine read_check_ionper(this) call store_error(errmsg) call this%parser%StoreErrorUnit() end if - ! - ! -- return - return end subroutine read_check_ionper !> @ brief Read griddata block for a package - !! - !! Generic method to read data in the GRIDDATA block for a package. - !! + !! + !! Generic method to read data in the GRIDDATA block for a package. + !! !< subroutine get_block_data(this, tags, lfound, varinames) ! -- modules @@ -296,9 +284,6 @@ subroutine get_block_data(this, tags, lfound, varinames) call this%parser%StoreErrorUnit() end if end do - ! - ! -- return - return end subroutine get_block_data end module NumericalPackageModule