On 29/04/2013 14:04, Helge Eichhorn wrote:
> Hi everybody,
>
> I am having problems documenting Fortran90 modules that contain nested
> interface blocks.
>
> When I run doxygen on the following minimal example the subroutines
> test2 and test3 become member functions of test in the documentation.
>
> Is this a bug or am I doing something wrong?
Hello Helge, I tested some variants of your code and I can confirm that
the doxygen Fortran parser gets confused when it encounters an interface
(even if undocumented) within a procedure declaration within an
interface, which is a legal construct in Fortran. As you say, what
happens in Doxygen is that the following module procedure is erroneously
treated as a member of the interface and not as a separate subroutine.
If I remove the interface to "dummy" subroutine things are interpreted
correctly.
I would classify this as "an unimplemented feature which triggers a bug,
rather than being silently ignored".
The point is that, in Fortran 90 and further, the INTERFACE keyword is
used, in my view, at least in 3 different contexts:
1) A (named) generic interface to specific procedures, tipically in a
module definition part. This is the context well supported by Doxygen,
which inteprets the interface as a compound data type with the specific
procedures as member functions.
2.1) An unnamed interface block containing many definitions of
independent interfaces, I think this is not worth having a special place
in the Doxygen hierarchy, it is a shorthand for grouping many interfaces
of the type described in the following 2.2 case.
2.2) A single explicit interface to a procedure, either providing an
abstract interface to a non existant procedure (F2003 or later) or
explicitely defining an interface for an external procedure which does
not have his own interface (F90 or later). In this case the interface
block is unnamed and only the subroutine or function has a name. I am
not sure whether Doxygen supports this construct and/or which would be
the correct way to support it.
3) An interface describing a procedure dummy argument which itself
corresponds to a procedure rather than to an ordinary variable; giving
an interface here, as opposed to defining the argument as "external",
allows the compiler to perform more compile-time checks for error in the
passed procedure argument. AFAIK this is equivalent, in C, to a function
pointer argument which is not generically void*() but has a specified
protptype (I may be wrong here due to my superficial knowledge of C).
The case proposed here is a nested case of type (3) within (2.1), but
due to the complexity of the subject and the lack of an official
maintainer of the Doxygen fortran parser I am afraid that this bug is
not going to be solved in a short time, I gave some contributions in the
past to the fortran parser, but due to my lack of knowledge of lex and
C++, I'm afraid I cannot give such a qualified help.
Best regards, Davide
>
> !> A module
> module doxytest
> interface
> !> A subroutine
> !! @param[out] a Output.
> !! @param dummy A dummy procedure.
> subroutine test(fun, a)
> interface
> !> A dummy procedure
> !! @param b Input
> subroutine dummy(b)
> real, intent(in) :: b
> end subroutine dummy
> end interface
> real, intent(out) :: a
> end subroutine test
>
> !> Another subroutine
> !! @param[in] c Input
> subroutine test2(c)
> real, intent(in) :: c
> end subroutine test2
> end interface
>
> contains
>
> !> A module procedure.
> !! @param[in] d Input
> subroutine test3(d)
> real, intent(in) :: d
> end subroutine test3
> end module doxytest
>
> Cheers,
> Helge
>
--
============================= Davide Cesari ============================
Dott**(0.5) Davide Cesari
ARPA-Emilia Romagna, Servizio IdroMeteoClima
NWP modelling - Modellistica numerica previsionale
========================================================================
------------------------------------------------------------------------------
Get 100% visibility into Java/.NET code with AppDynamics Lite
It's a free troubleshooting tool designed for production
Get down to code-level detail for bottlenecks, with <2% overhead.
Download for free and get started troubleshooting in minutes.
http://p.sf.net/sfu/appdyn_d2d_ap2
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
