如何让Doxygen与Fortran接口语句配合使用？

Question

我正在为自由软件项目CCR工作，它允许气候和其他地球科学用户向netCDF添加额外的压缩方法。请查看https://github.com/ccr/ccr。

我有一个Fortran文件，但Doxygen给了我以下警告：

/home/ed/noaa/ccr/fsrc/ccr.F90:19: warning: Member nc_def_var_bzip2(ncid, varid, level) (function) of class ccr::nc_def_var_bzip2 is not documented.
/home/ed/noaa/ccr/fsrc/ccr.F90:36: warning: Member nc_def_var_lz4(ncid, varid, level) (function) of class ccr::nc_def_var_lz4 is not documented.
/home/ed/noaa/ccr/fsrc/ccr.F90:27: warning: Member nc_inq_var_bzip2(ncid, varid, bzip2p, levelp) (function) of class ccr::nc_inq_var_bzip2 is not documented.
/home/ed/noaa/ccr/fsrc/ccr.F90:44: warning: Member nc_inq_var_lz4(ncid, varid, lz4p, levelp) (function) of class ccr::nc_inq_var_lz4 is not documented.

但我已经记录了这些功能。Doxygen抱怨的行号是接口声明的一部分：

module ccr

  !> Interface to initialization function.
  interface
     function nc_initialize_ccr() bind(c)
       use iso_c_binding
     end function nc_initialize_ccr
  end interface

  !> Interface to C function to set BZIP2 compression.
  interface
     function nc_def_var_bzip2(ncid, varid, level) bind(c)
       use iso_c_binding
       integer(C_INT), value :: ncid, varid, level
     end function nc_def_var_bzip2
  end interface

  !> Interface to C function to inquire about BZIP2 compression.
  interface
     function nc_inq_var_bzip2(ncid, varid, bzip2p, levelp) bind(c)
       use iso_c_binding
       integer(C_INT), value :: ncid, varid
       integer(C_INT), intent(inout):: bzip2p, levelp
     end function nc_inq_var_bzip2
  end interface

  !> Interface to C function to set LZ4 compression.
  interface
     function nc_def_var_lz4(ncid, varid, level) bind(c)
       use iso_c_binding
       integer(C_INT), value :: ncid, varid, level
     end function nc_def_var_lz4
  end interface

  !> Interface to C function to inquire about LZ4 compression.
  interface
     function nc_inq_var_lz4(ncid, varid, lz4p, levelp) bind(c)
       use iso_c_binding
       integer(C_INT), value :: ncid, varid
       integer(C_INT), intent(inout):: lz4p, levelp
     end function nc_inq_var_lz4
  end interface

如何让 Doxygen 看到接口的文档？

- Edward Hartnett

---

你试过将注释移到接口块中吗？ - Vladimir F Героям слава

Doxygen 手册 的 "Documentation at other places" 部分可能包含你正在寻找的答案。我没有尝试过，但解决方案可能就像在注释开头添加 \interface 一样简单。 - PetrH

Doxygen 抱怨接口中定义的方法没有文档，但我觉得接口已经有文档了，难道我漏掉了什么吗（也许可以添加一张图片并指出你缺少的内容）。您使用的是哪个版本的 Doxygen？ - albert

Answer 1

答案是使用@fn标签，并在module_name :: fn_name ::之后指定整个函数签名。以下是来自另一个项目的示例：

  interface
     !> @fn bacio_module::baciol::baciol(mode, start, newpos, size, no, nactual, fdes, fname, datary)
     !> Do a bacio operation.
     !>
     !> @param mode
     !> @param start
     !> @param newpos
     !> @param size
     !> @param no
     !> @param nactual
     !> @param fdes
     !> @param fname
     !> @param datary
     !>
     !> @author Ed Hartnett @date 21-10-18
     integer function baciol(mode, start, newpos, size, no, nactual, &
          fdes, fname, datary) bind(C)
       use, intrinsic :: iso_c_binding
       integer(c_int), value, intent(in) :: mode
       integer(c_long), value, intent(in) :: start, newpos
       integer(c_int), value, intent(in) :: size
       integer(c_long), value, intent(in) :: no
       integer(c_long), intent(inout) :: nactual
       integer(c_int), intent(inout) :: fdes
       character(kind=C_char), intent(in) :: fname(*)
       character(kind=C_char), intent(in) :: datary(*)
     end function baciol
  end interface

- Edward Hartnett

---

能否在这里使用\copydoc或\snippet{doc}呢？ - albert