Commits

Harald Klimach  committed 97b8657

Improved documenting comments for aot_out_module

  • Participants
  • Parent commits ec8348c

Comments (0)

Files changed (1)

File source/aot_out_module.f90

 !> A module to produce Lua scripts with nested tables.
 !!
 !! This module eases the output of readable Lua scripts.
-!! It takes care of indentation with nested tables, and
-!! provides a concise interface to output Fortran data
-!! into Lua scripts.
-!! Therefore this module is somehow the counter-part to
-!! the reading functions, however it is almost completely
-!! independent and relies purely on Fortran output methods.
+!! It takes care of indentation with nested tables, and provides a concise
+!! interface to output Fortran data into Lua tables.
+!! Therefore this module is somehow the counter-part to the reading functions,
+!! however it is almost completely independent and relies purely on Fortran
+!! output methods. Thus this module could stand alone, along with the
+!! aot_kinds_module without the Lua library.
 module aot_out_module
 
   use aot_kinds_module
   end type
 
   !> Put Fortran intrinsic types into the script.
+  !!
+  !! Scalar values and one-dimensional arrays are supported.
+  !! Supported data-types are
+  !! - integer
+  !! - integer(kind=long_k)
+  !! - real
+  !! - real(kind=double_k)
+  !! - logical
+  !! - character(len=*)
+  !! complex values are not supported, as they are indistinguishable from
+  !! arrays with two entries on the Lua side.
   interface aot_out_val
+    ! scalars
     module procedure aot_out_val_int
     module procedure aot_out_val_long
     module procedure aot_out_val_real
     module procedure aot_out_val_double
     module procedure aot_out_val_logical
     module procedure aot_out_val_string
+
+    ! arrays
     module procedure aot_out_val_arr_int
     module procedure aot_out_val_arr_long
     module procedure aot_out_val_arr_real
 contains
 
 !******************************************************************************!
-!> Open the file to write to and return a handle (put_conf) to it.
-!!
-!! This will overwrite the given file, if it already exists.
-!! Either filename of outUnit has to be specified, use outUnit to write to a
-!! pre-connected file.
-!! If both are given, the file will be opened and connected to a new unit,
-!! outUnit is ignored in this case.
+  !> Open the file to write to and return a handle (put_conf) to it.
+  !!
+  !! This will overwrite the given file, if it already exists.
+  !! Either filename of outUnit has to be specified, use outUnit to write to a
+  !! pre-connected file.
+  !! If both are given, the file will be opened and connected to a new unit,
+  !! outUnit is ignored in this case.
   subroutine aot_out_open(put_conf, filename, outUnit, indentation)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(out) :: put_conf !< Handle for the file
       open(unit = put_conf%outunit, file = trim(filename), action = 'write', &
         &  status='replace', recl=360)
       put_conf%externalOpen = .false.
-    else if ( present(outUnit) ) then
+    else if (present(outUnit)) then
       put_conf%externalOpen = .true.
       put_conf%outunit = outUnit
-!HK!    else
-!HK!       write(*,*) 'Error, no unit or filename specified for aot_open_put'
-!HK!       stop
-!HK: Return an error code instead.
     end if
 
     put_conf%indent = 0
 
 
 !******************************************************************************!
-!>  Close the script again.
-!!
+  !>  Close the opened script again.
+  !!
+  !! This will close the file, if the data was not written to a pre-connected
+  !! unit (that is the file for the script was opened in the aot_out_open).
   subroutine aot_out_close(put_conf)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!> Start a new table to write to.
-!!
+  !> Start a new table to write to.
+  !!
+  !! You can give the table a name with the tname argument.
+  !! If the table definition should NOT start on a new line, you have to pass
+  !! in an advance_previous = .false.
   subroutine aot_out_open_table(put_conf, tname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Close the current table.
-!!
+  !>  Close the current table.
+  !!
+  !! The table on the current table is closed with a curly bracket.
+  !! If this bracket should be put to the same line as the last entry of the
+  !! table, you have to set advance_previous = .false.
   subroutine aot_out_close_table(put_conf, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put integer variables into the Lua script.
-!!
+  !>  Put integer variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_int(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put long variables into the Lua script.
-!!
+  !>  Put long variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_long(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put real variables into the Lua script.
-!!
+  !>  Put real variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_real(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put double variables into the Lua script.
-!!
+  !>  Put double variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_double(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put logical variables into the Lua script.
-!!
+  !>  Put logical variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_logical(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!>  Put string variables into the Lua script.
-!!
+  !>  Put string variables into the Lua script.
+  !!
+  !! The value is passed in with path, optionally you can assign a name to it
+  !! with the vname argument. If it should be put on the same line as the
+  !! previous entry, you have to set advance_previous=.false.
   subroutine aot_out_val_string(put_conf, val, vname, advance_previous)
     !------------------------------------------------------------------------
     type(aot_out_type), intent(inout)  :: put_conf
 
 
 !******************************************************************************!
-!> This is a vectorized version of the value output.
-!!
-!! It takes a one-dimensional array and puts it into a table. The parameters
-!! have the usual meanings, as in the scalar routines, however and additional
-!! argument (max_per_line) allows the specification of the number of elements
-!! that might be put onto a single line.
-!! The first entry will be placed into the same line as the opening brace, and
-!! the closing brace will be put on the same line, as the last entry.
+  !> This is a vectorized version of the value output.
+  !!
+  !! It takes a one-dimensional array and puts it into a table. The parameters
+  !! have the usual meanings, as in the scalar routines, however and additional
+  !! argument (max_per_line) allows the specification of the number of elements
+  !! that might be put onto a single line.
+  !! The first entry will be placed into the same line as the opening brace, and
+  !! the closing brace will be put on the same line, as the last entry.
   subroutine aot_out_val_arr_int(put_conf, val, vname, advance_previous, &
     &                            max_per_line)
     !------------------------------------------------------------------------
 
 
 !******************************************************************************!
-!> This is a vectorized version of the value output.
-!!
-!! It takes a one-dimensional array and puts it into a table. The parameters
-!! have the usual meanings, as in the scalar routines, however and additional
-!! argument (max_per_line) allows the specification of the number of elements
-!! that might be put onto a single line.
-!! The first entry will be placed into the same line as the opening brace, and
-!! the closing brace will be put on the same line, as the last entry.
+  !> This is a vectorized version of the value output.
+  !!
+  !! It takes a one-dimensional array and puts it into a table. The parameters
+  !! have the usual meanings, as in the scalar routines, however and additional
+  !! argument (max_per_line) allows the specification of the number of elements
+  !! that might be put onto a single line.
+  !! The first entry will be placed into the same line as the opening brace, and
+  !! the closing brace will be put on the same line, as the last entry.
   subroutine aot_out_val_arr_long(put_conf, val, vname, advance_previous, &
     &                             max_per_line)
     !------------------------------------------------------------------------
 
 
 !******************************************************************************!
-!> This is a vectorized version of the value output.
-!!
-!! It takes a one-dimensional array and puts it into a table. The parameters
-!! have the usual meanings, as in the scalar routines, however and additional
-!! argument (max_per_line) allows the specification of the number of elements
-!! that might be put onto a single line.
-!! The first entry will be placed into the same line as the opening brace, and
-!! the closing brace will be put on the same line, as the last entry.
+  !> This is a vectorized version of the value output.
+  !!
+  !! It takes a one-dimensional array and puts it into a table. The parameters
+  !! have the usual meanings, as in the scalar routines, however and additional
+  !! argument (max_per_line) allows the specification of the number of elements
+  !! that might be put onto a single line.
+  !! The first entry will be placed into the same line as the opening brace, and
+  !! the closing brace will be put on the same line, as the last entry.
   subroutine aot_out_val_arr_real(put_conf, val, vname, advance_previous, &
     &                             max_per_line)
     !------------------------------------------------------------------------
 
 
 !******************************************************************************!
-!> This is a vectorized version of the value output.
-!!
-!! It takes a one-dimensional array and puts it into a table. The parameters
-!! have the usual meanings, as in the scalar routines, however and additional
-!! argument (max_per_line) allows the specification of the number of elements
-!! that might be put onto a single line.
-!! The first entry will be placed into the same line as the opening brace, and
-!! the closing brace will be put on the same line, as the last entry.
+  !> This is a vectorized version of the value output.
+  !!
+  !! It takes a one-dimensional array and puts it into a table. The parameters
+  !! have the usual meanings, as in the scalar routines, however and additional
+  !! argument (max_per_line) allows the specification of the number of elements
+  !! that might be put onto a single line.
+  !! The first entry will be placed into the same line as the opening brace, and
+  !! the closing brace will be put on the same line, as the last entry.
   subroutine aot_out_val_arr_double(put_conf, val, vname, advance_previous, &
     &                               max_per_line)
     !------------------------------------------------------------------------
 
 
 !******************************************************************************!
-!> This subroutine takes care of the proper linebreaking in Lua-Tables.
-!!
-!! It takes care of a proper line-continuation, depending on the optional
-!! advance_previous flag and increases the count of elements in the current
-!! table.
+  !> This subroutine takes care of the proper linebreaking in Lua-Tables.
+  !!
+  !! It takes care of a proper line-continuation, depending on the optional
+  !! advance_previous flag and increases the count of elements in the current
+  !! table.
+  !! The default is to put each entry on a new line, if it should be on the
+  !! same line advance_previous = .false. has to be set.
   subroutine aot_out_breakline(put_conf, advance_previous)
     type(aot_out_type), intent(inout)  :: put_conf
     logical, optional, intent(in) :: advance_previous