如何使用 Doxygen 和 Doxygen::Filter::Perl 为 Perl 子例程生成文档？

Posted 2023-03-24

【中文标题】如何使用 Doxygen 和 Doxygen::Filter::Perl 为 Perl 子例程生成文档？

【英文标题】：How to use Doxygen and Doxygen::Filter::Perl to generate documentation for Perl sub routines?

【发布时间】：2015-05-16 00:37:05

【问题描述】：

我正在尝试弄清楚如何使用Doxygen::Filter::Perl 为 Perl 文件生成文档。我从一个非常简单的文件开始，只是为了看看我是否可以让它工作（test_doxygen.pl）：

#! /usr/bin/env perl
#** @file test_doxygen.pl
#  @brief  Testing Doxygen using Doxygen::Filter::Perl
#
# Description of the purpose of this file
#
#  @author Håkon Hægland ([e-mail])
#
#  @bug No known bugs.
#
#*

#** @class main
# The main class
#*

use strict;
use warnings;

my $b = add_one(1);

#** @function public add_one ($par1)
# @brief A brief description of the function
#
# A detailed description of the function
# @params $par1   required  A number
# @retval value   Input value plus one1
#*
sub add_one 
    my ($par1) = @_;

    return $par1 + 1;

然后我安装了 Doxygen::Filter::Perl 并使用了 metacpan.org (the link is here) 的包维护者提供的 Doxyfile 配置文件 并将其放在与上面脚本相同的目录中。我在Doxyfile中更改了一行：INPUT标签的值从lib改为空字符串，以便只搜索当前目录的源文件..

我使用的是Ubuntu 14.04，所以我用sudo apt-get install doxygen安装了Doxygen，（我还需要安装graphviz:sudo apt-get install graphviz）然后我终于运行了

$ doxygen

从终端窗口。生成的 html 文件 doc/html/index.html 包含有关文件和作者的文档，但它不包含 add_one 子例程的任何文档。

我在这里错过了什么？

更新

以下是 Chromium 浏览器中类视图的外观：

正如所见，add_one 子例程没有引用/链接。

这是文件视图：

【问题讨论】：

您错过了 Perl 程序员使用 pod 的想法？

@mob 读完这个***.com/questions/4722619/… 我决定试试 Doxygen :)

【参考方案1】：

所以问题在于处理“我的”变量声明。它将值设置为私有：并且 doxygen 从未返回。我在 Perl.pm 中添加了一行来解决这个问题，它现在应该对你有用。由于您使用的是 pl 文件而不是 pm 文件，因此我还对 Doxyfile 进行了更改，因此您将希望从发行版中获取新文件。我已将 1.71 发布到 Github 和 CPAN，并使用您的确切示例对其进行了测试。

【讨论】：

谢谢乔丹。它现在正在工作！看起来不错，感谢您抽出宝贵时间。

【参考方案2】：

我刚刚将 Doxygen::Filter::Perl 的新版本发布到 Github 和 CPAN，版本 1.70。这应该可以解决您看到的问题。

【讨论】：

谢谢@jordan2175。但它仍然不起作用。我运行cpanm Doxygen::Filter::Perl 更新到1.70 版。然后重新运行doxygen 命令，但我仍然得到相同的结果。在浏览器的类视图或文件视图中没有add_one 子例程..

【参考方案3】：

我刚刚看了这个，它似乎可以与 Doxygen (1.7.5.1) 一起使用，但是，较新版本的 Doxygen (1.8.9.1) 似乎不能很好地工作。

【讨论】：

谢谢@jordan2175。我使用的是 1.8.6 版。