Re: Whither Fortran type-bound procedure documentation?

Matthew,

Thank you for the example.
I see indeed a feature tthat is not supported yet in doxygen:
generic,   public :: wibble => wibble_integer, wibble_real

It will take a it of time before I can have a good look at this problem.


Albert


On Thu, Sep 22, 2016 at 3:45 PM, Hambley, Matthew <
[email protected]> wrote:

> From: Albert [mailto:[email protected]]
> >
> > 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.
>

------------------------------------------------------------------------------

_______________________________________________
Doxygen-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/doxygen-users