Commits

Manuel Hasert committed 871d2ee Merge

merge

Comments (0)

Files changed (6)

source/aot_fun_module.f90

 !> A module providing access to Lua functions
 !!
-!! Intended usage:
-!! First open a function with aot_fun_open
-!! Then put required parameters inot it with
-!! aot_fun_put
-!! Execute the function with aot_fun_do
-!! Retrieve the possibly multiple results with
-!! aot_top_get_val.
-!! Repeat putting and retrieving if needed.
-!! Close the function again with aot_fun_close.
+!! Intented usage:
+!!
+!! - First open a function with aot_fun_open.
+!! - Then put required parameters into it with aot_fun_put.
+!! - Execute the function with aot_fun_do().
+!! - Retrieve the possibly multiple results with
+!!   AOT_top_module::aot_top_get_val.
+!! - Repeat putting and retrieving if needed.
+!! - Close the function finally with aot_fun_close().
 module aot_fun_module
   use flu_binding
   use aot_kinds_module, only: double_k, single_k
 
   !> Open a Lua function for evaluation.
   !!
-  !! After it is opened, arguments might be
-  !! put into the function, and it might be
-  !! executed. This might be repeated for
-  !! an arbitrary number to retrieve more than
-  !! one evaluation of a single function, before
-  !! closing it again with aot_fun_close.
+  !! After it is opened, arguments might be put into the function, and it might
+  !! be executed.
+  !! Execution might be repeated for an arbitrary number of iterations, to
+  !! retrieve more than one evaluation of a single function, before closing it
+  !! again with aot_fun_close().
   interface aot_fun_open
     module procedure aot_fun_global
     module procedure aot_fun_table
 
   !> Put an argument into the lua function.
   !!
-  !! Arguments have to be in order, first put
-  !! the first argument then the second and so on.
+  !! Arguments have to be in order, first put the first argument then the second
+  !! and so on.
   interface aot_fun_put
     module procedure aot_fun_put_double
   end interface aot_fun_put
 
 contains
 
+
   !> Return the stack of the top as a function.
   !!
-  !! If it actually is not a Lua function, its handle
-  !! will be set to 0.
+  !! If it actually is not a Lua function, the returned handle will be 0.
   function aot_fun_top(L) result(fun)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> Handle to the function on the top of the stack.
     type(aot_fun_type) :: fun
 
     fun%handle = 0
     end if
   end function aot_fun_top
 
+
   !> Get a globally defined function.
   subroutine aot_fun_global(L, fun, key)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> Returned handle, providing access to the function.
     type(aot_fun_type), intent(out) :: fun
+
+    !> Name of the function to look up in the global scope of the Lua script.
     character(len=*), intent(in) :: key
 
     call flu_getglobal(L, key)
     fun = aot_fun_top(L)
   end subroutine aot_fun_global
 
+
   !> Get a function defined as component of a table.
+  !!
+  !! Functions in tables might be retrieved by position or key.
+  !! If both optional parameters are provided, the key is attempted to be read
+  !! first, only if that fails, the position will be tested.
   subroutine aot_fun_table(L, parent, fun, key, pos)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> Handle to the table to look in for the function.
     integer, intent(in) :: parent
+
+    !> Returned handle, providing access to the function.
     type(aot_fun_type), intent(out) :: fun
+
+    !> Name of the function to look up in the table.
     character(len=*), intent(in), optional :: key
+
+    !> Position of the function to look up in the table.
     integer, intent(in), optional :: pos
 
     call aot_table_push(L, parent, key, pos)
     fun = aot_fun_top(L)
   end subroutine aot_fun_table
 
-  !> Close the function again (pop everything
-  !! above from the stack).
+
+  !> Close the function again (pop everything above from the stack).
   subroutine aot_fun_close(L, fun)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> Handle to the function to close.
     type(aot_fun_type) :: fun
 
     if (fun%handle > 0) call flu_settop(L, fun%handle-1)
     fun%arg_count = 0
   end subroutine aot_fun_close
 
-  !> Put an argument of type double into the list
-  !! of arguments for the function.
+
+  !> Put an argument of type double into the list of arguments for the function.
+  !!
+  !! Currently only double precision reals are supported.
   subroutine aot_fun_put_double(L, fun, arg)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> Handle of the function, this argument should be put into.
     type(aot_fun_type) :: fun
+
+    !> Actual argument to hand over to the Lua function.
     real(kind=double_k), intent(in) :: arg
 
     if (fun%handle /= 0) then
     end if
   end subroutine aot_fun_put_double
 
-  !> Execute a given function and put its results
-  !! on the stack, where it is retrievable with
-  !! aot_top_get_val.
+
+  !> Execute a given function and put its results on the stack, where it is
+  !! retrievable with AOT_top_module::aot_top_get_val.
+  !!
+  !! The optional arguments ErrCode and ErrString provide some feedback on the
+  !! success of the function execution.
+  !! If none of them are in the argument list, the execution of the application
+  !! will be stopped, and the error will be printed to the standard output.
   subroutine aot_fun_do(L, fun, nresults, ErrCode, ErrString)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> Handle to the function to execute.
     type(aot_fun_type) :: fun
+
+    !> Number of resulting values the caller wants to obtain from the Lua
+    !! function.
     integer, intent(in) :: nresults
+
+    !> Error code returned by Lua during execution of the function.
     integer, intent(out), optional :: ErrCode
+
+    !> Obtained error string from the Lua stack if an error occured.
     character(len=*), intent(out), optional :: ErrString
 
     integer :: err

source/aot_path_module.f90

 
   end subroutine aot_path_open_fun
 
+
   !> This subroutine opens all the tables on the way to the final head node of
   !! the given path.
   !!
 
   end subroutine aot_path_open_table
 
+
   !> This routine closes function and all other tables opened along the path.
   subroutine aot_path_close_fun(me, conf, fun, closeLua)
     !> The path object to open as a function
 
   end subroutine aot_path_close_fun
 
+
   !> This routine closes all the table opened in aot_path_open_table.
   subroutine aot_path_close_table(me, conf, closeLua)
     !> The path object to open as a function

source/aot_table_module.f90

-!> This module provides some convenient functions to act
-!! on lua tables.
+!> This module provides some convenient functions to act on Lua tables.
 module aot_table_module
   use flu_binding
   use aot_kinds_module, only: double_k, single_k, long_k
 
   !> Get a value from a table.
   !!
-  !! First the given !! key is looked up, if this fails, the value
+  !! First the given key is looked up, if this fails, the value
   !! at the given position is looked up, and if this also fails,
   !! the default value is returned.
   !! Positional addressing is only valid, as long,
     module procedure get_table_logical
   end interface
 
+  !> Get a value from a table.
+  !!
+  !! First the given key is looked up, if this fails, the value
+  !! at the given position is looked up, and if this also fails,
+  !! the default value is returned.
+  !! Positional addressing is only valid, as long,
+  !! as no value was provided by an explicit key
+  !! in the list before the entry in question.
+  !!
+  !! The interface to access table values looks like:
+  !! `call aot_get_val(val, errCode, L, thandle, key, pos, default)`.
+  !! Position pos and key are both optional, but one of them has to be provided.
+  !! If both are provided the key takes precedence over the pos, and the pos
+  !! will only be tried if the access to the key fails.
+  !! See for example get_table_real() for a more detailed
+  !! description of the parameters.
+  !!
+  !! Note that positional addressing only works intuitively as long as there
+  !! have been no entries specified by keys in the table.
+  !! This kind of resembles the behavior of Fortran interfaces with named or
+  !! unnamed arguments, as soon as you provide a name, all following arguments
+  !! have to be given by key also.
+  !! Just stick to this rule for the Lua tables as well to avoid too much
+  !! headache.
+  !!
+  !! The reason for this is, that positional addressing in Lua refers only to
+  !! the unnamed entries of the tables.
   interface aot_get_val
     module procedure get_table_real
     module procedure get_table_double
   !! for further operations on that table.
   !! Otherwise a 0 will be returned.
   function aot_table_top(L) result(thandle)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> A handle for the table on the top of the stack to access it.
     integer :: thandle
+
     if (flu_isNoneOrNil(L, -1) .or. (.not. flu_isTable(L, -1))) then
       thandle = 0
       call flu_pop(L)
   !! table. If it does not exist or the global variable is not
   !! a table, the handle will be set to 0.
   subroutine aot_table_global(L, thandle, key)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> A handle for the table to access it, 0 if no table available.
     integer, intent(out) :: thandle
+
+    !> Name of the global table to access.
     character(len=*), intent(in) :: key
 
     call flu_getglobal(L, key)
 
   !> This subroutine tries to get a table in a table, and
   !! return a handle for it.
+  !!
+  !! Return its position in the stack as a handle for this
+  !! table. If it does not exist or the table entry is not
+  !! a table itself, the handle will be set to 0.
+  !! The table can be looked up either by position or name.
   subroutine aot_table_table(L, parent, thandle, key, pos)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> Handle of the table containing the requested table.
     integer, intent(in) :: parent
+
+    !> A handle for the table to access it, 0 if no table available.
     integer, intent(out) :: thandle
+
+    !> Name of the entry in the parent table to access.
+    !!
+    !! The key takes precedence over the position, if both are provided.
+    !! In this case the positional address is only tried, if the access to the
+    !! key failed.
     character(len=*), intent(in), optional :: key
+
+    !> Position of the entry in the parent table to access.
     integer, intent(in), optional :: pos
 
     call aot_table_push(L, parent, key, pos)
   !!
   !! This is done by popping all values above and itself from the stack.
   subroutine aot_table_close(L, thandle)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> Handle of the table to close.
     integer, intent(in) :: thandle
 
     if (thandle > 0) call flu_settop(L, thandle-1)
   end subroutine aot_table_close
 
 
-  !> This subroutine tries to push the value of table thandle on
-  !! the lua stack, or if this fails, the entry at position pos
-  !! of the table. If no corresponding value is found, a nil
-  !! value is pushed to the stack.
+  !> This subroutine tries to push the value of the entry given by key or pos
+  !! within the table thandle on the lua stack.
+  !!
+  !! If no corresponding value is found, a nil value is pushed to the stack.
+  !! Key and pos are both optional, but one of them has to be supplied. If one
+  !! is supplied, the key is checked first and only if this fails the entry at
+  !! pos will be looked up.
   subroutine aot_table_push(L, thandle, key, pos)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> Handle to the table to look in.
     integer :: thandle
+
+    !> Name of the entry to push to the stack.
     character(len=*), intent(in), optional :: key
+
+    !> Position of the entry to push to the stack.
     integer, intent(in), optional :: pos
 
     if (thandle /= 0) then
   !! If there are no entries in the table the function
   !! returns false, otherwise the result will be true.
   function aot_table_first(L, thandle) result(exists)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> Handle to the table to get the first entry of.
     integer, intent(in) :: thandle
+
+    !> The return value signals, if there actually is such a first entry.
     logical :: exists
 
     if (thandle /= 0) then
 
   !> Count the entries in a lua table.
   function aot_table_length(L, thandle) result(length)
-    type(flu_state) :: L
+    type(flu_state) :: L !< Handle for the Lua script.
+
+    !> Handle of the table to count the enries in.
     integer, intent(in) :: thandle
+
+    !> Returns the number of entries in the table.
     integer :: length
 
     length = 0
   end function aot_table_length
 
 
+  !> Retrieve a single precision real value from a table.
   subroutine get_table_real(val, ErrCode, L, thandle, key, pos, default)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script.
+
+    !> Handle to the table to look the value up in.
     integer, intent(in) :: thandle
+
+    !> Value of the table entry if it exists.
     real(kind=single_k), intent(out) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
 
+    !> Name of the entry to look for.
+    !!
+    !! Key and pos are both optional, however at least one of them has to be
+    !! supplied.
+    !! The key takes precedence over the pos if both are given.
     character(len=*), intent(in), optional :: key
+
+    !> Position of the entry to look for in the table.
+    !!
+    !! It allows the access to unnamed arrays in the Lua tables.
     integer, intent(in), optional :: pos
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     real(kind=single_k), intent(in), optional :: default
 
     call aot_table_push(L=L, thandle=thandle, &
   end subroutine get_table_real
 
 
+  !> Retrieve a double precision real value from a table.
   subroutine get_table_double(val, ErrCode, L, thandle, key, pos, &
     &                         default)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script.
+
+    !> Handle to the table to look the value up in.
     integer, intent(in) :: thandle
+
+    !> Value of the table entry if it exists.
     real(kind=double_k), intent(out) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
 
+    !> Name of the entry to look for.
+    !!
+    !! Key and pos are both optional, however at least one of them has to be
+    !! supplied.
+    !! The key takes precedence over the pos if both are given.
     character(len=*), intent(in), optional :: key
+
+    !> Position of the entry to look for in the table.
+    !!
+    !! It allows the access to unnamed arrays in the Lua tables.
     integer, intent(in), optional :: pos
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     real(kind=double_k), intent(in), optional :: default
 
     call aot_table_push(L=L, thandle=thandle, &
   end subroutine get_table_double
 
 
+  !> Retrieve a default integer value from a table.
   subroutine get_table_integer(val, ErrCode, L, thandle, key, pos, &
     &                          default)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script.
+
+    !> Handle to the table to look the value up in.
     integer, intent(in) :: thandle
+
+    !> Value of the table entry if it exists.
     integer, intent(out) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
 
+
+    !> Name of the entry to look for.
+    !!
+    !! Key and pos are both optional, however at least one of them has to be
+    !! supplied.
+    !! The key takes precedence over the pos if both are given.
     character(len=*), intent(in), optional :: key
+
+    !> Position of the entry to look for in the table.
+    !!
+    !! It allows the access to unnamed arrays in the Lua tables.
     integer, intent(in), optional :: pos
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     integer, intent(in), optional :: default
 
     call aot_table_push(L=L, thandle=thandle, &
 
   end subroutine get_table_integer
 
+
+  !> Retrieve a long integer value from a table.
   subroutine get_table_long(val, ErrCode, L, thandle, key, pos, default)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script.
+
+    !> Handle to the table to look the value up in.
     integer, intent(in) :: thandle
+
+    !> Value of the table entry if it exists.
     integer(kind=long_k), intent(out) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
 
+    !> Name of the entry to look for.
+    !!
+    !! Key and pos are both optional, however at least one of them has to be
+    !! supplied.
+    !! The key takes precedence over the pos if both are given.
     character(len=*), intent(in), optional :: key
+
+    !> Position of the entry to look for in the table.
+    !!
+    !! It allows the access to unnamed arrays in the Lua tables.
     integer, intent(in), optional :: pos
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     integer(kind=long_k), intent(in), optional :: default
 
     call aot_table_push(L=L, thandle=thandle, &
 
   end subroutine get_table_long
 
+
+  !> Retrieve a logical value from a table.
   subroutine get_table_logical(val, ErrCode, L, thandle, key, pos, &
     &                          default)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script.
+
+    !> Handle to the table to look the value up in.
     integer, intent(in) :: thandle
+
+    !> Value of the table entry if it exists.
     logical, intent(out) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
 
+    !> Name of the entry to look for.
+    !!
+    !! Key and pos are both optional, however at least one of them has to be
+    !! supplied.
+    !! The key takes precedence over the pos if both are given.
     character(len=*), intent(in), optional :: key
+
+    !> Position of the entry to look for in the table.
+    !!
+    !! It allows the access to unnamed arrays in the Lua tables.
     integer, intent(in), optional :: pos
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     logical, intent(in), optional :: default
 
     call aot_table_push(L=L, thandle=thandle, &
   end subroutine get_table_logical
 
 
+  !> Retrieve a string from a table.
   subroutine get_table_string(val, ErrCode, L, thandle, key, pos, &
     &                         default)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script.
+
+    !> Handle to the table to look the value up in.
     integer, intent(in) :: thandle
+
+    !> Value of the table entry if it exists.
     character(len=*) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
 
+    !> Name of the entry to look for.
+    !!
+    !! Key and pos are both optional, however at least one of them has to be
+    !! supplied.
+    !! The key takes precedence over the pos if both are given.
     character(len=*), intent(in), optional :: key
+
+    !> Position of the entry to look for in the table.
+    !!
+    !! It allows the access to unnamed arrays in the Lua tables.
     integer, intent(in), optional :: pos
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     character(len=*), intent(in), optional :: default
 
     call aot_table_push(L=L, thandle=thandle, &

source/aot_top_module.f90

-!> Module for interaction with topmost element of Luas stack.
+!> Module for interaction with topmost element of the Lua stack.
+!!
+!! This is a basic module which provides the fundamental functionality to
+!! access the topmost element in the stack of the Lua API.
+!! All intrinsic variables except complex numbers can be accessed this way.
 module aot_top_module
   use flu_binding
   use aot_kinds_module, only: double_k, single_k, long_k
   !! They indicate the bits to set in case of
   !! the corresponding error, to allow appropiate
   !! reactions of the calling application.
+  !! As a bitmask is used to encode the error, and combination of them
+  !! might be returned.
   integer, parameter :: aoterr_Fatal = 0
   integer, parameter :: aoterr_NonExistent = 1
   integer, parameter :: aoterr_WrongType = 2
   !! that it does not matter how the value
   !! actually gets on top of the stack by
   !! previous Lua operations.
+  !!
+  !! The interface looks like this:
+  !! `call aot_top_get_val(val, errCode, L, default)`.
+  !! See for example aot_top_get_real() for a more detailed
+  !! description of the parameters.
+  !!
+  !! The aot_top_get_val can not be in the same generic interface as the other
+  !! aot_get_val routines, as it results in ambiguities of the interfaces.
   interface aot_top_get_val
     module procedure aot_top_get_real
     module procedure aot_top_get_double
     module procedure aot_top_get_logical
   end interface
 
-  interface aot_get_val
-    module procedure aot_top_get_real
-    module procedure aot_top_get_double
-    module procedure aot_top_get_integer
-    module procedure aot_top_get_long
-    module procedure aot_top_get_string
-    module procedure aot_top_get_logical
-  end interface
-
-
 contains
 
+  !> Interpret topmost entry on Lua stack as a single precision real.
+  subroutine aot_top_get_real(val, ErrCode, L, default)
+    type(flu_State) :: L !< Handle to the Lua script
 
-  subroutine aot_top_get_real(val, ErrCode, L, default)
-    type(flu_State) :: L
+    !> Value of the Variable in the script
     real(kind=single_k), intent(out) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     real(kind=single_k), optional, intent(in) :: default
 
     logical :: not_retrievable
   end subroutine aot_top_get_real
 
 
+  !> Interpret topmost entry on Lua stack as a double precision real.
   subroutine aot_top_get_double(val, ErrCode, L, default)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script
+
+    !> Value of the Variable in the script
     real(kind=double_k), intent(out) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     real(kind=double_k), optional, intent(in) :: default
 
     logical :: not_retrievable
   end subroutine aot_top_get_double
 
 
+  !> Interpret topmost entry on Lua stack as a default integer.
   subroutine aot_top_get_integer(val, ErrCode, L, default)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script
+
+    !> Value of the Variable in the script
     integer, intent(out) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     integer, optional, intent(in) :: default
 
     logical :: not_retrievable
 
   end subroutine aot_top_get_integer
 
+
+  !> Interpret topmost entry on Lua stack as a single precision real.
   subroutine aot_top_get_long(val, ErrCode, L, default)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script
+
+    !> Value of the Variable in the script
     integer(kind=long_k), intent(out) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     integer(kind=long_k), optional, intent(in) :: default
 
     logical :: not_retrievable
 
   end subroutine aot_top_get_long
 
+
+  !> Interpret topmost entry on Lua stack as a single precision real.
   subroutine aot_top_get_logical(val, ErrCode, L, default)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script
+
+    !> Value of the Variable in the script
     logical, intent(out) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     logical, optional, intent(in) :: default
 
     logical :: not_retrievable
   end subroutine aot_top_get_logical
 
 
+  !> Interpret topmost entry on Lua stack as a single precision real.
   subroutine aot_top_get_string(val, ErrCode, L, default)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script
+
+    !> Value of the Variable in the script
     character(len=*) :: val
+
+    !> Error code to indicate what kind of problem might have occured.
     integer, intent(out) :: ErrCode
+
+    !> Some default value, that should be used, if the variable is not set in
+    !! the Lua script.
     character(len=*), optional, intent(in) :: default
 
     logical :: not_retrievable
   end subroutine aot_top_get_string
 
 
+  !> Error handler to capture Lua errors.
+  !!
+  !! This routine encapsulates the retrieval of error messages from the Lua
+  !! stack upon a failing Lua operation.
+  !! It should be be used after all flu functions, that return an err as result.
+  !! Such as flu_binding::fluL_loadfile and flu_binding::flu_pcall.
+  !! The ErrString and ErrCode parameters are both optional if none of them are
+  !! provided, the execution will be stopped if an error had occured and err is
+  !! not 0. The error message will be written to standard output in this case.
+  !!
+  !! If either of them are provide, the application will continue, and the
+  !! calling side has to deal with the occured error.
   subroutine aot_err_handler(L, err, msg, ErrString, ErrCode)
-    type(flu_State) :: L
+    type(flu_State) :: L !< Handle to the Lua script
+
+    !> Lua error code to evaluate
     integer, intent(in) :: err
+
+    !> Some additional message that should be prepended to the Lua error
+    !! message.
     character(len=*), intent(in) :: msg
+
+    !> Resulting error string obtained by combination of msg and the error
+    !! description on the Lua stack.
     character(len=*), intent(out), optional :: ErrString
+
+    !> The Lua error code, just the same as err.
     integer, intent(out), optional :: ErrCode
 
     logical :: stop_on_error

source/aot_vector_module.f90

 !> This module provides some convenience functions to access complete vectors
 !! from a lua table at once.
 !!
-!! It provides to generic interfaces, one for vectors inside tables, and one
+!! It provides two generic interfaces, one for vectors inside tables, and one
 !! for vectors defined as global variables (get_config_val).
 !! Vectors might be accessed with a variable length, to be defined by the
 !! Lua table and allocated in the get_ routines or with a fixed length.
   !!
   !! Arrays will be allocated as needed to read the data from the
   !! Lua script with these routines. A maximal length has to be
-  !! specified to limit the allocated memory by this loading.
+  !! specified to limit the allocated memory by these routines (and make the
+  !! interfaces distinguishable).
   interface aot_get_val
     module procedure get_config_real_vvect
     module procedure get_config_double_vvect
   !!
   !! The given vector has to exist already and will be filled by
   !! values from the Lua table, as far as they exist.
+  !! If the Lua table is longer than the available elements in the array
+  !! only the first elements from the table will be stored in the array.
   interface aot_get_val
     module procedure get_config_real_v
     module procedure get_config_double_v

source/aotus_module.f90

   !!                    the requested data type
   !!
   !! For example a check for a fatal error can be done by
-  !! <tt>btest(errCode, aoterr_fatal)</tt>.
+  !! `btest(errCode, aoterr_fatal)`.
   !!
   !! For the access to global variables in the Lua script the interface
   !! therefore looks like:
-  !! <tt>call aot_get_val(val, errCode, L, key, default)</tt>.
+  !! `call aot_get_val(val, errCode, L, key, default)`.
   !! See for example aotus_module#get_config_real for a more detailed
   !! description of the parameters.
   interface aot_get_val