1 原生doxygen對python註釋的文件化支援情況

預設情況下，doxygen可以同時支援兩種風格的python註釋，原生的docstring和類似java doc風格的##。不過實際使用時不是十全十美

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

類似java doc風格的##

#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass
 

• 可惜的是，對原生的docstring，在函式多行定義的時候，不僅經常提取不到註釋，而且即使提取到註釋，也不支援各種註釋tag，如@param，@see等。
• 對java doc風格的##，雖然支援較好，可惜的是偶使用的是pydev做IDE工具的，pydev顯示函式註釋資訊總是錯位的，提取的是下一個函式的註釋。

2. input filter：doxypypy

幸運的是，有牛人提供了一個doxygen的input filter，用於把原生docstring轉換為java doc風格的##。https://github.com/Feneric/doxypypy。注意還有一個類似的叫doxypy的工具，是現在這個工具的前身，那個工具問題不少。

這裡先簡單介紹一下doxygen的input filter的功能，簡單一句話描述就是一個文字的預處理。當你定義了input filter之後，doxygen在生成文件時就不會直接讀取檔案內容，而是先呼叫input filter處理檔案內容，然後將處理結果作為doxygen自己的輸入。

再簡單介紹一下doxypypy這個工具的工作原理：簡單來說就是先提取出docstring，然後去掉docstring開頭和結尾的""", 然後插入##作為第一行，再在其餘各行註釋前面加上#，這樣就很簡單巧妙的轉換為類java doc的##風格了。將轉換後的結果作為doxygen的輸入，就可以製作出漂亮的文件了。

# As close as possible to a direct copy of the sample in PEP 257 and still
# be valid code. Simple as can be.

complex_zero = 0j


def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    else:
        return complex(real, imag)

# As close as possible to a direct copy of the sample in PEP 257 and still
# be valid code. Simple as can be.

complex_zero = 0j


##Form a complex number.
#
#    Keyword arguments:
#    real -- the real part (default 0.0)
#    imag -- the imaginary part (default 0.0)
#
#
def complex(real=0.0, imag=0.0):
    if imag == 0.0 and real == 0.0:
        return complex_zero
    else:
        return complex(real, imag)

# As close as possible to a direct copy of the sample in PEP 257 and still
# be valid code. Simple as can be.

complex_zero = 0j


## @brief Form a complex number.
#
#
# @param		real	the real part (default 0.0)
# @param		imag	the imaginary part (default 0.0)
#
#
# @namespace sample_pep.complex
def complex(real=0.0, imag=0.0):
    if imag == 0.0 and real == 0.0:
        return complex_zero
    else:
        return complex(real, imag)

3 新增doxypypy對中文的支援

解釋的話稍微多了點，下面說一下中文支援。原生的doxypypy工具不支援中文。想鄙人這種沒有專業八級英語的，寫的註釋有時還不如不寫。不過要支援也簡單，使用下面這個補丁。不多說，就兩點：使用codecs按utf-8編碼格式讀入，將標準輸出的編碼設定為utf-8。

diff --git a/doxypypy/doxypypy.py b/doxypypy/doxypypy.py
old mode 100755
new mode 100644
index 833a723..76ca6be
--- a/doxypypy/doxypypy.py
+++ b/doxypypy/doxypypy.py
@@ -20,6 +20,8 @@
 from os import linesep
 from string import whitespace
 from codeop import compile_command
+import codecs
+import sys
 
 
 def coroutine(func):
@@ -820,15 +822,17 @@
 
     # Figure out what is being requested.
     (options, inFilename) = optParse()
-
+    
+    file_encoding = 'utf-8'
     # Read contents of input file.
-    inFile = open(inFilename)
+    inFile = codecs.open(inFilename, encoding=file_encoding)
     lines = inFile.readlines()
     inFile.close()
     # Create the abstract syntax tree for the input file.
     astWalker = AstWalker(lines, options, inFilename)
     astWalker.parseLines()
     # Output the modified source.
+    sys.stdout = codecs.getwriter(file_encoding)(sys.stdout.buffer, 'strict')
     print(astWalker.getLines())
 
 # See if we're running as a script.

4 在doxygen中配置doxypypy

最後說一下如何在doxygen中配置上面工具，直接上圖片。注意：doxypypy.py的第一行表示的是python的安裝路徑，注意修改為自己電腦上的python路徑。

如果需要下載修改過的doxypypy.py, 可以在這裡下載doxypypy--- Doxygen filter for Python

that‘s all