我可以用doxygen记录Python代码（有没有意义）？ [英] Can I document Python code with doxygen (and does it make sense)?

问题描述

我喜欢doxygen来创建C或PHP代码的文档。我有一个即将到来的Python项目，我想我记得Python没有/ * .. * /评论，还有自己的自我文档设施，似乎是pythonic的方式来记录。

我可以只使用doxygen吗？有什么特别要注意的吗？

我已经在Python中做了一些编码，但到目前为止，只有在我懒惰的小项目中，我才知道（是的，我知道...但是现在我们假装现在没问题了。

解决方案

这是 ，但总结如下：

您可以使用doxygen记录您的Python代码。您可以使用Python文档字符串语法：

 @ package docstring 
此模块的文档
 
更多细节

 
 def func（）：
函数的文档
 
更多细节

 pass 
  

在这种情况下，评论将由doxygen提取，但您将无法使用任何特殊doxygen命令。

或可以（类似于doxygen下的C风格语言）将注释标记（<$在成员之前的第一行，c $ c>＃）

  ## @package pyexample 
＃此模块的文档。 
＃
＃更多细节。 
 
 ##函数的文档。 
＃
＃更多细节。 
 def func（）：
 pass 
  

在这种情况下，您可以使用特殊的doxygen命令。没有特定的Python输出模式，但您可以通过将 OPTMIZE_OUTPUT_JAVA 设置为 YES 来显着改善结果。

老实说，我有点惊讶的区别 - 似乎一旦doxygen可以检测到##块或块中的评论，大部分的工作将完成，您可以在任何一种情况下使用特殊命令，也许他们希望有人使用来遵守更多的Pythonic文档实践，这会干扰特殊的doxygen命令？

I like doxygen to create documentation of C or PHP code. I have an upcoming Python project and I think I remember that Python doesn't have /* .. */ comments and also has its own self-documentation facility which seems to be the pythonic way to document.

Can I just use doxygen? Anything particular to be aware of?

I have done some coding in Python but so far only on small projects where I was to lazy to document at all (yeah, I know ... but let's just pretend that's OK for now).

解决方案

This is documented on the doxygen website, but to summarize here:

You can use doxygen to document your Python code. You can either use the Python documentation string syntax:

"""@package docstring
Documentation for this module.

More details.
"""

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

    More details.
    """
    pass

In which case the comments will be extracted by doxygen, but you won't be able to use any of the special doxygen commands.

Or you can (similar to C-style languages under doxygen) double up the comment marker (#) on the first line before the member:

## @package pyexample
#  Documentation for this module.
#
#  More details.

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

In that case, you can use the special doxygen commands. There's no particular Python output mode, but you can apparently improve the results by setting OPTMIZE_OUTPUT_JAVA to YES.

Honestly, I'm a little surprised at the difference - it seems like once doxygen can detect the comments in ## blocks or """ blocks, most of the work would be done and you'd be able to use the special commands in either case. Maybe they expect people using """ to adhere to more Pythonic documentation practices and that would interfere with the special doxygen commands?

这篇关于我可以用doxygen记录Python代码（有没有意义）？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！