如何检查 doxygen \return 语句的正确性？答案

【问题标题】：How to check correctness of doxygen \return statements?如何检查 doxygen \return 语句的正确性？
【发布时间】：2013-08-27 14:10:40
【问题描述】：

我在 cmets 中继承了一些带有 doxygen 注释的 C 源代码。由于位腐烂，\return 注释的一些注释现在是谎言，即一个函数已被转换为返回 void，但\return 注释仍然存在并另有说明。

例子：

/*!
 * \brief   The foo function
 * \return  OK if successful, ERROR otherwise
 */
void foo(void)
{
    ...
}

现在我想找到所有这样的文件。我想过使用 grep/sed/awk/perl 来查找\return，然后打印以void 开头的下一行。一个简单的

 grep -E '(\\return|^void)' file ...

还打印来自非空函数的所有\return cmets。如果看到^void 行，我确信有一种简单的方法仅打印上一个\return 行。

【问题讨论】：

请反对者详细说明我的问题有什么问题？

标签： c perl sed awk doxygen

【解决方案1】：

如果您的所有函数及其前面的 cmets 都遵循您发布的样式，这可能就是您所需要的：

awk '/\\return/{cmt=$0} /^[[:alpha:]]/{ if (/^void/ && cmt) print cmt ORS $0; cmt=""}' file

例如：

$ cat file
/*!
 * \brief   The foo function
 * \return  OK if successful, ERROR otherwise
 */
void foo(void)
{
    ...
}

/*!
 * \brief   The bar function
 * \return  OK if successful, ERROR otherwise
 */
int bar(void)
{
    ...
}

$ awk '/\\return/{cmt=$0} /^[[:alpha:]]/{ if (/^void/ && cmt) print cmt ORS $0; cmt=""}' file
 * \return  OK if successful, ERROR otherwise
void foo(void)

【讨论】：

【解决方案2】：

#! /usr/bin/env perl

use strict;
use warnings;

my $prev_return;

while (<>) {
  # assume letter in first column introduces a function return type
  if (my($return_type) = /^([^\W\d]\w*)/) {
    if ($return_type eq "void" && defined $prev_return) {
      print $prev_return;
    }
    undef $prev_return;  # reset after each function definition
  }
  elsif (/\\return\b/) {
    $prev_return = "$ARGV:$.: $_";
  }
}
continue {
  close ARGV if eof;  # reset $. at the end of each named file
}

注意：模式[^\W\d] 使用double-negative technique 来匹配不是数字的“单词字符”，即、字母和下划线。

样本输出：

$ cat file.c
/*！
 * \brief foo 函数
 * \成功则返回OK，否则返回ERROR
 */
无效富（无效）
{
    ...
}

\return fdsklj
空栏（空）

无效的巴兹

$ ./doxygen-return-void 文件.c
file.c:3: * \如果成功则返回 OK，否则返回 ERROR
file.c:10: \return fdsklj

Perl 的 <>，也称为菱形运算符，使编写 Unix 风格的过滤器变得容易。这意味着您可以命名任意多的路径。

$ ./doxygen-return-void file.c file.c
file.c:3: * \如果成功则返回 OK，否则返回 ERROR
file.c:10: \return fdsklj
file.c:3: * \如果成功则返回 OK，否则返回 ERROR
file.c:10: \return fdsklj

上面的程序也会消耗标准输入，但输出并不是很有用。

$ cat file.c | ./doxygen-return-void
-:3: * \如果成功则返回OK，否则返回ERROR
-:10: \return fdsklj

【讨论】：