From: Albert [mailto:albert.te...@gmail.com] > > 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.
test_mod.f90
Description: test_mod.f90
------------------------------------------------------------------------------
_______________________________________________ Doxygen-users mailing list Doxygen-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/doxygen-users
