Provide information about tensor finalizer (#522)

* FAQ about warnings
* Provide some additional information about tensor finalizer
* Provide link to Fortran-lang learn section on OO-Fortran
* Reference common warnings section for finalizer warning
* Refer to f08/0011 for technical details
* Text specific to structure finalizer

Author: joewallwork

pages/usage/tensor.md

@@ -88,12 +88,25 @@ the other methods (simply drop the preceding `torch_tensor_`).
 #### Deallocation
 
 We provide a subroutine for deallocating the memory associated with a
-[[ftorch_tensor(module):torch_tensor(type)]] object:
-[[ftorch_tensor(module):torch_tensor_delete(subroutine)]].
-An interface is provided such that this can also be applied to arrays of tensors.
-Calling this subroutine manually is optional as it is called as a destructor
-when a [[ftorch_tensor(module):torch_tensor(type)]] goes out of scope.
-
+[[ftorch(module):torch_tensor(type)]] object:
+[[ftorch(module):torch_tensor_delete(subroutine)]]. An interface
+[[ftorch(module):torch_delete(interface)]] is provided such that this can also
+be applied to arrays of tensors.
+
+Manually deallocating a tensor that you declared and constructed in your code is
+actually optional. If the tensor was declared in a subroutine then
+[[ftorch(module):torch_tensor_delete(subroutine)]] will get called as the
+finalizer of [[ftorch(module):torch_tensor(type)]] when it goes out of scope. If
+the tensor was declared in a program then the finalizer won't get called, but
+this is not considered to be an issue, in the same way that in Fortran it
+doesn't matter if allocated arrays aren't deallocated at the end of the program.
+Note that if you are building FTorch with gfortran and the 2008 standard then
+you may see a warning related to finalizers - see the
+[common warnings entry](|page|/usage/troubleshooting.html#finalizer-with-fortran-2008)
+for more information.
+
+See the [Fortran-lang page on object-oriented Fortran](https://fortran-lang.org/learn/oop_features_in_fortran/object_based_programming_techniques/#finalization-and-conclusions)
+for further details about finalization.
 
 #### Manipulation
 

pages/usage/troubleshooting.md

@@ -10,6 +10,7 @@ If you are experiencing problems building or using FTorch please see below for g
 - [Common Errors](#common-errors)
     - [No specific subroutine](#no-specific-subroutine)
     - [Segmentation faults](#segmentation-faults)
+- [Common warnings](#common-warnings)
 
 
 ### Usage
@@ -97,3 +98,50 @@ the overloaded assignment operator should be triggered. As such, if you aren't
 using the bare `use ftorch` import then you should ensure you specify
 `use ftorch, only: assignment(=)` (as well as any other module members you
 require). See the [tensor documentation](|page|/usage/tensor.html) for more details.
+
+
+### Common warnings
+
+#### Structure constructor finalizer with Fortran 2008
+
+If you are building FTorch with gfortran and are specifying the Fortran 2008
+standard (e.g., with the compiler flag `-std=f2008` or by default) then you may
+get compiler warnings of the form:
+```
+Warning: The structure constructor at (1) has been finalized. This feature was removed by f08/0011. Use -std=f2018 or -std=gnu to eliminate the finalization.
+```
+These warn that the structure finalizer of the
+[[ftorch(module):torch_tensor(type)]] derived type is triggered when a tensor
+goes out of scope, despite the fact that this feature was removed from the 2008
+standard. That is, the [[ftorch(module):torch_tensor_delete(subroutine)]]
+subroutine is called so that the associated memory is automatically freed.
+Firstly, this is the behaviour that we want so we should not be too concerned.
+Secondly, structure finalizers are not used anywhere in FTorch, so we believe
+this warning to be errorneous. Use of the structure constructor for the
+`torch_tensor` type would be something like
+```fortran
+program
+  use, intrinsic :: iso_c_binding, only: c_null_ptr
+  use ftorch
+  implicit none
+  type(torch_tensor) :: tensor
+
+  tensor = torch_tensor(c_null_ptr)
+end program
+```
+While this code would compile successfully, the warning mentioned above would be
+raised.
+
+@warning
+The code snippet above is **not** the intended way to create a tensor. The
+intended way is to use the provided API procedures such as
+[[ftorch(module):torch_tensor_from_array(interface)]] or
+[[ftorch(module):torch_tensor_ones(subroutine)]]. The code snippet above is
+only intended to illustrate the use of the structure constructor and the
+associated warning.
+@endwarning
+
+See the [tensor documentation](|page|/usage/tensor.html#deallocation) for more
+details on the memory management of tensors and the use of the finalizer. For
+technical details on `f08/0011`, we refer to
+[https://wg5-fortran.org/N2001-N2050/N2006.txt](https://wg5-fortran.org/N2001-N2050/N2006.txt).