我刚刚从Django开始一个项目,并且想为Python函数编写类似下面的javadoc片段的内容.我已经看到我可以使用Sphinx或reStructuredText,但似乎功能太强大了.用Python执行此操作的正常方法是什么？

我的目标不是在文档中生成很大的pdf / html,而是在调用方法时让我的IDE(pyCharm)显示文档.

 /**
  * 
  * @param p1
  * @param p2
  * @param p3
  * @return ...
  */

解决方法:

我在Django和普通Python项目上广泛使用了IntellJ IDEA / PyCharm.

肯定要使用reStructuredText和Sphinx,只有在您要生成HTML或PDF文档时才使用后者.这也是Python库本身的记录方式.几个月前,我从epydoc切换到reStructuredText,因为后者提供了更好的一般支持.

您的文档字符串如下所示：

def myfunc(p1, p2, p3):
    """myfunc does something interesting.

    some more detail. See :meth:`my_other_func` for more information.

    :param p1: The first parameter.
    :type p1: string
    :param p2: The second parameter.
    :param p3: The third parameter.
    :returns: True if successful, False if not.
    """

    my_code(p1)
    more_code(p2)
    return third_part(p1,p2,p3)

它与旧的epydoc标准中的基本元素没有太大区别. PyCharm可以解析此信息,例如,使用：type：specs在函数主体中完成操作.