如何檢查doxygen \ return語句的正確性？

Question

我在註釋中繼承了一些帶有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意見。我確信有一個簡單的方法來只有打印以前的\return行，如果看到^void行。

Answer 1

這可能是你所需要的，如果所有的功能和其前面的評論是你貼的風格：

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) 

Answer 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 The foo function 
* \return OK if successful, ERROR otherwise 
*/ 
void foo(void) 
{ 
    ... 
} 

\return fdsklj 
void bar(void) 

void baz 

$ ./doxygen-return-void file.c 
file.c:3: * \return OK if successful, ERROR otherwise 
file.c:10: \return fdsklj

Perl的<>，又稱鑽石操作，使得編寫Unix風格的過濾器容易。這意味着您可以根據需要命名儘可能多的路徑。

$ ./doxygen-return-void file.c file.c 
file.c:3: * \return OK if successful, ERROR otherwise 
file.c:10: \return fdsklj 
file.c:3: * \return OK if successful, ERROR otherwise 
file.c:10: \return fdsklj

上面的程序也將消耗標準輸入，但輸出不是非常有用。

$ cat file.c | ./doxygen-return-void 
-:3: * \return OK if successful, ERROR otherwise 
-:10: \return fdsklj