Add documentation

Author: sethrj

Doc/Manual/src/Fortran.md

@@ -1890,9 +1890,92 @@ void should_be_wrapped(UnknownType*);
 
 ## Cross-language polymorphism using directors
 
+The "director" capability in SWIG allows C++ classes to be subclassed by a
+user in the target language to enable inversion of control through overridden
+C++ virtual functions. For Fortran, this means that a SWIG-wrapped
+derived type can be *extended* by an application code so that C++ code can send
+data to a native Fortran type-bound procedure and receive data back.
+
+Enabling this advanced and still highly experimental feature requires extra
+SWIG directives, including a special setup argument in the `%module`
+declaration.
+```swig
+%module(directors="1") example
+
+%feature("director") Base;
+
+%inline %{
+class Base {
+ public:
+  virtual ~Base() {}
+  virtual int apply(int x) const = 0;
+};
+
+int apply(const Base& b, int x) {
+  return b.apply(x);
+}
+%}
+```
+
+This allows a user application to declare an extended type such as:
+```fortran
+module mymod
+  use, intrinsic :: ISO_C_BINDING
+  use ISO_FORTRAN_ENV
+  use example, only : Base
+  implicit none
+
+  type, extends(Base), public :: MyDerived
+    integer(C_INT) :: multiply_by = 1
+    integer(C_INT) :: add_to = 0
+  contains
+    procedure :: apply => MyDerived_apply
+  end type MyDerived
+contains
+ 
+function MyDerived_apply(self, x) &
+  result(myresult)
+  use, intrinsic :: ISO_C_BINDING
+  class(MyDerived), intent(in) :: self
+  integer(C_INT), intent(in) :: x
+  integer(C_INT) :: myresult
+
+  myresult = x * self%multiply_by + self%add_to
+end function
+end module
+```
+
+The overridden procedure can be called either from Fortran *or* through
+existing C++ library code.
+```fortran
+subroutine test_director_int
+  use director_simple
+  use director_simple_mod
+  use, intrinsic :: ISO_C_BINDING
+  type(MyDerived), target :: myclass
+
+  ! Allocate and set up callbacks for Base class
+  call swig_initialize(myclass, source=Base())
+  myclass%multiply_by = 2
+  myclass%add_to = 1
+
+  ! Direct Fortran call
+  ASSERT(myclass%apply(10_c_int) == 21_c_int)
+  ! Call through C director
+  ASSERT(apply(myclass, 10_c_int) == 21_c_int)
+
+  call myclass%release()
+end subroutine
+```
+
+### Limitations
+
+Currently only fundamental types are supported.
+
 Fortran has much less introspection than Java, Python, and other less static
 languages. Therefore director methods can't automatically detect whether the
-target language (Fortran) overrides a particular method.
+target language (Fortran) overrides a particular method. **Therefore you must
+currently override all virtual methods.**
 
 Note that a bug in GCC prevents versions before 8 from using the
 `--std=f2003` flag (see [GNU bug 84924](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=84924)).