doxygen-users

[Doxygen-users] two problems with Fortran interfaces

[Alfredo B. <alf...@en...>]

Dear all,
I am trying to use doxygen for documenting a code written in Fortran
90/95. I am facing a few problems with interfaces.
Take the following two files:


File sub.f90:

!>  @brief suba is a routine that does a
!!  @param[in]  n is an integer argument
!!  @param[out] f as well
subroutine suba(n, f)
  integer :: n, f
  return
end subroutine suba

!>  @brief subb is a routine that does b
!!  @param[in]  n is a real argument
subroutine subb(n)
  real :: n
  return
end subroutine subb




File submod.f90:

module submod
  !> @brief generic interface for the @link suba @endlink and @link
  !! subb @endlink routines
  interface sub
     subroutine suba(n, f)
       integer :: n, f
     end subroutine suba
     subroutine subb(n)
       integer :: n
     end subroutine subb
  end interface
end module submod




The optput of Doxygen on these two files has two major problems:

1) the "sub" generic interface appears in the Data Types List which is
obviously wrong

2) all the hyperlinks to "suba" and "subb" in the pages related to the
module or the interface should bring to the definition of those
routines into the sub.f90 file but instead the are directed to some
place inside submod.f90.


Does anybody know whether this is actually a doxygen problem? or, am I
doing anything wrong?

Thanks in advance

Alfredo




-- 
-----------------------------------------
Alfredo Buttari, PhD
CNRS-IRIT
2 rue Camichel, 31071 Toulouse, France
http://buttari.perso.enseeiht.fr

Re: [Doxygen-users] two problems with Fortran interfaces

[Oleg B. <og...@gm...>]

Hi Alfredo,

> The optput of Doxygen on these two files has two major problems:
>
> 1) the "sub" generic interface appears in the Data Types List which is
> obviously wrong

Fortran extension is based on what is available in Doxygen from C and
C++ . There is no direct analogue for Fortran interfaces, so it was
chosen to use Sections::CLASS_SEC with ClassSpecifier::Interface. This
places the interface into Data Type List as if it was C/C++ class and
marks it as "interface" on its documentation page.

This is an old issue: https://bugzilla.gnome.org/show_bug.cgi?id=521859

> 2) all the hyperlinks to "suba" and "subb" in the pages related to the
> module or the interface should bring to the definition of those
> routines into the sub.f90 file but instead the are directed to some
> place inside submod.f90.
Everywhere outside the interface (documentation) it does link to those
subroutines. If you want to link to those subroutines inside the
interface use ::suba and ::subb.
May be it should be done automatically but not sure.

See also latest changes to Fortran interfaces in Doxygen
https://bugzilla.gnome.org/show_bug.cgi?id=637610

Oleg

> Take the following two files:
>
>
> File sub.f90:
>
> !>  @brief suba is a routine that does a
> !!  @param[in]  n is an integer argument
> !!  @param[out] f as well
> subroutine suba(n, f)
>  integer :: n, f
>  return
> end subroutine suba
>
> !>  @brief subb is a routine that does b
> !!  @param[in]  n is a real argument
> subroutine subb(n)
>  real :: n
>  return
> end subroutine subb
>
>
>
>
> File submod.f90:
>
> module submod
>  !> @brief generic interface for the @link suba @endlink and @link
>  !! subb @endlink routines
>  interface sub
>     subroutine suba(n, f)
>       integer :: n, f
>     end subroutine suba
>     subroutine subb(n)
>       integer :: n
>     end subroutine subb
>  end interface
> end module submod
>
>
>
> Does anybody know whether this is actually a doxygen problem? or, am I
> doing anything wrong?
>
> Thanks in advance
>
> Alfredo
>
>
>
>
> --
> -----------------------------------------
> Alfredo Buttari, PhD
> CNRS-IRIT
> 2 rue Camichel, 31071 Toulouse, France
> http://buttari.perso.enseeiht.fr
>
> ------------------------------------------------------------------------------
> Enable your software for Intel(R) Active Management Technology to meet the
> growing manageability and security demands of your customers. Businesses
> are taking advantage of Intel(R) vPro (TM) technology - will your software
> be a part of the solution? Download the Intel(R) Manageability Checker
> today! http://p.sf.net/sfu/intel-dev2devmar
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>

Re: [Doxygen-users] two problems with Fortran interfaces

[Alfredo B. <alf...@en...>]

Dear Oleg,
thanks for the very detailed answers to my questions. Everything you
say makes a lot of sense. The little trick of using ::suba and ::subb
is a nice solution to my second problem and, as you suggest, I believe
it should be done automatically, although I realize it may be
difficult to do it (if possible at all).

Best regards

Alfredo




On Thu, Mar 31, 2011 at 12:51 PM, Oleg Batrashev <og...@gm...> wrote:
> Hi Alfredo,
>
>> The optput of Doxygen on these two files has two major problems:
>>
>> 1) the "sub" generic interface appears in the Data Types List which is
>> obviously wrong
>
> Fortran extension is based on what is available in Doxygen from C and
> C++ . There is no direct analogue for Fortran interfaces, so it was
> chosen to use Sections::CLASS_SEC with ClassSpecifier::Interface. This
> places the interface into Data Type List as if it was C/C++ class and
> marks it as "interface" on its documentation page.
>
> This is an old issue: https://bugzilla.gnome.org/show_bug.cgi?id=521859
>
>> 2) all the hyperlinks to "suba" and "subb" in the pages related to the
>> module or the interface should bring to the definition of those
>> routines into the sub.f90 file but instead the are directed to some
>> place inside submod.f90.
> Everywhere outside the interface (documentation) it does link to those
> subroutines. If you want to link to those subroutines inside the
> interface use ::suba and ::subb.
> May be it should be done automatically but not sure.
>
> See also latest changes to Fortran interfaces in Doxygen
> https://bugzilla.gnome.org/show_bug.cgi?id=637610
>
> Oleg



-- 
-----------------------------------------
Alfredo Buttari, PhD
CNRS-IRIT
2 rue Camichel, 31071 Toulouse, France
http://buttari.perso.enseeiht.fr