Re: [Doxygen-users] Whither Fortran type-bound procedure documentation?

[Hambley, M. <mat...@me...>]

From: Albert [mailto:alb...@gm...]
> 
> Can you create a small  example to show the short comings?

Of course. What follows is a Fortran module which should illustrate what I am trying to describe. (Object Fortran is, sadly, never short)

Having carefully laid it out I suddenly had a nasty realisation that Outlook is probably about to mangle it horrible so I've attached a copy as well. Skip past the source code for commentary.

module test_mod

  use iso_fortran_env, only : output_unit

  implicit none

  private

  !> @brief Type which does a thing
  !> @details Documented where we would expect.
  !>
  type, public :: test_type

    private

    integer, allocatable :: foo(:)

  contains

    private
    !> @brief Document in the type declaration
    !> @details Not so good as there are no arguments here. If they are
    !>          documented here they show up in documentation but Doxygen
    !>          complains about them being documented but not existing. Of
    !>          course they do, but further down.
    !>
    !>          Regardless the documentation is separate from the
    !>          implementation.
    !> @param teapot Some argument.
    !>
    procedure, public :: wobble
    procedure, public :: wubble
    generic,   public :: wibble => wibble_integer, wibble_real

    !> @brief One aspect of wibble
    !> @details I can document this here but it appears as a method of
    !>          the type whereas really it should appear under
    !>          "wibble". After all, it is private and not part of the
    !>          API.
    !>
    procedure wibble_integer
    procedure wibble_real

    final :: destroy_test

  end type test_type

  interface test_type
    procedure create_test_default
    !> @brief Specific initialiser
    !> @details Will this how up? No it will not.
    procedure create_test_specific
  end interface test_type

contains

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !> @brief Default initialiser
  !>
  !> @details It would be nice to document this here but it wont show up.
  !>
  function create_test_default() result(new_test)

    implicit none

    type(test_type) :: new_test

    allocate( new_test%foo(10) )
  end function create_test_default

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
function create_test_specific( tally ) result(new_test)

    implicit none

    integer, intent(in) :: tally

    type(test_type) :: new_test

    allocate( new_test%foo(tally) )

  end function create_test_specific

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !> @brief Destructor.
  !> @details Would prefer to document this here.
  !>
  subroutine destroy_test( this )

    implicit none
    type(test_type), intent(inout) :: this

    deallocate( this%foo )

  end subroutine destroy_test

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !> @brief A more sensible place to document.
  !> @details But it does not appear.
  !> @param teapot Some other argument.
  !>
  subroutine wobble( this, teapot )

    implicit none

    class(test_type), intent(in) :: this
    integer,          intent(in) :: teapot

    write( output_unit, '("wobble ", I0)' ) teapot

  end subroutine wobble

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  subroutine wubble( this, cheese )

    implicit none

    class(test_type), intent(in) :: this
    integer,          intent(in) :: cheese

    write( output_unit, '("wubble ", I0)' ) cheese

  end subroutine wubble

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  subroutine wibble_integer( this, value )

    implicit none

    class(test_type), intent(inout) :: this
    integer,         intent(in) :: value

    write( output_unit, '("wibble ", I0)' ) value

  end subroutine wibble_integer

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !> @brief Again I would like to document this here.
  !> @details But again it will not show up.
  !> @param value A floating point argument.
  !>
  subroutine wibble_real( this, value )

    implicit none

    class(test_type), intent(inout) :: this
    real,            intent(in) :: value

    write( output_unit, '("wibble ", F14.4)' ) value

  end subroutine wibble_real

end module test_mod

Running this through Doxygen I get the following messages:

test_mod.f90:29: warning: Member wubble (function) of class test_mod::test_type is not documented.

Of course it is, but at the definition rather than the declaration.

test_mod.f90:30: warning: Member wibble=> wibble_integer, wibble_real (function) of class test_mod::test_type is not documented.

This is sort of true except wibble is documented by wibble_integer and wibble_real.

test_mod.f90:38: warning: Member wibble_real (function) of class test_mod::test_type is not documented.

It is, but further down.

test_mod.f90:40: warning: Member destroy_test (function) of class test_mod::test_type is not documented.

Again, it is, but further down.

test_mod.f90:13: warning: Member foo (variable) of class test_mod::test_type is not documented.

True but irrelevant to the current issue.

test_mod.f90:22: warning: argument 'teapot' of command @param is not found in the argument list of test_mod::test_type::wobble()

It does, but at definition, not declaration.

I realise that this is all pretty esoteric stuff and that there isn't a lot of object Fortran around but if you can suggest a solution I would be very grateful.