标签: documentation

我最近开始学习Python,但我找不到如何实现多行注释.大多数语言都有块注释符号

/* 

*/

我在Python中试过这个,但它会抛出一个错误,所以这可能不是正确的方法.Python实际上是否具有多行注释功能？

我在Python中看到过几种不同的写作文档字符样式,是官方还是"同意"的风格？

我的团队开始使用 doxygen 记录我们的 C 代码，特别关注我们的公共 API 标头。doxygen 中似乎有很多灵活性和不同的特殊命令，这很棒，但如果没有反复试验，就不清楚什么是好事，什么是坏事。

您最喜欢的标记代码的方式是什么？您必须做什么和不应该做什么？
请提供您的重要提示，每个答案一个，以方便投票。

我希望定义 API 文档的整个方法，包括提供一个模板来让团队的其他成员开始。到目前为止我有这样的事情：

/**
 * @file   example_action.h
 * @Author Me (me@example.com)
 * @date   September, 2008
 * @brief  Brief description of file.
 *
 * Detailed description of file.
 */

/**
 * @name    Example API Actions
 * @brief   Example actions available.
 * @ingroup example
 *
 * This API provides certain actions as an example.
 *
 * @param [in] repeat  Number of times to do nothing.
 *
 * @retval TRUE   Successfully did nothing. …

我有一位同事坚持认为他的代码不需要评论,而是"自我记录".

我已经回顾了他的代码,虽然它比我见过其他代码生成的代码更清晰,但我仍然不同意自我编写代码是完整和有用的以及评论和记录的代码.

帮助我理解他的观点.

• 什么是自我记录代码
• 它真的可以取代评论和记录良好的代码
• 是否存在比记录良好和注释的代码更好的情况
• 是否存在代码无法在没有注释的情况下进行自我记录的示例

也许这只是我自己的局限,但我不知道它是如何成为一种好的做法.

这并不是一个争论 - 请不要提出为什么评论和记录良好的代码是高优先级的原因 - 有很多资源显示这一点,但它们并不能让我的同行相信.我相信我需要更充分地理解他的观点来说服他.如果必须,请开始一个新问题,但不要在此争论.

哇,快速反应!请阅读所有现有答案,并为答案提供评论,而不是添加新答案,除非您的答案与此处的其他答案完全不同.

此外,那些反对自我记录代码的人 - 这主要是为了帮助我理解自我记录代码福音传道者的观点(即积极方面).如果你不留下话题,我希望别人会贬低你.

一个Xcode中5的新功能是一种特殊的注释语法来记录自己的代码的能力.格式类似于doxygen,但似乎只支持这些功能的子集.

支持哪些命令,哪些命令不支持？
他们的任何用法与doxygen有什么不同？

所以我完全理解如何使用resample,但文档并没有很好地解释选项.

所以resample函数中的大多数选项都很简单,除了这两个:

• rule:表示目标转换的偏移字符串或对象
• how:string,down-or-sampling的方法,默认为'mean'

因此,通过查看我在网上找到的尽可能多的示例,我可以看到规则,你可以做'D'一天,'xMin'几分钟,'xL'几毫秒,但这就是我能找到的.

对我怎么看到以下内容:'first',np.max,'last','mean',和'n1n2n3n4...nx'其中nx为每列索引的第一个字母.

那么在我缺少的文档中是否有某个地方显示了pandas.resample规则和输入的每个选项？如果是的话,因为我找不到它.如果不是,那么他们的选择是什么？

我目前从Python开始,我有一个强大的PHP背景,在PHP中我习惯使用javadoc作为文档模板.

我想知道它是否javadoc有它作为docstringPython文档的位置.这里有既定的惯例和/或官方的guildelines？

例如,这样的东西太精巧,不适合Python的思维方式,或者我应该尽量简洁？

"""
replaces template place holder with values

@param string timestamp     formatted date to display
@param string priority      priority number
@param string priority_name priority name
@param string message       message to display

@return string formatted string
"""

如果我有点过于详尽,我应该选择这样的东西(大多数文档不通过该__doc__方法打印)？

# replaces template place holder with values
#    
# @param string timestamp     formatted date to display
# @param string priority      priority number
# @param string priority_name priority name
# @param string message …

好的,所以我已经阅读了PEP 8和PEP 257,并且我已经为函数和类编写了很多文档字符串,但是我对模块文档字符串中的内容有点不确定.我想,至少它应该记录模块导出的函数和类,但我也看到了一些列出作者姓名,版权信息等的模块.有没有人有一个好的python文档字符串如何应该的例子结构化？

我目前正在编写一个小框架,将由公司内部的其他开发人员在内部使用.

我想提供良好的Intellisense信息,但我不知道如何记录抛出的异常.

在以下示例中:

public void MyMethod1()
{
    MyMethod2();

    // also may throw InvalidOperationException
}

public void MyMethod2()
{
    System.IO.File.Open(somepath...); // this may throw FileNotFoundException

    // also may throw DivideByZeroException
}

我知道记录异常的标记是:

/// <exception cref="SomeException">when things go wrong.</exception>

我不明白的是如何记录被调用的 代码引发的异常MyMethod1()？

• 我应该记录引发的异常吗？ MyMethod2()
• 我应该记录引发的异常File.Open()吗？

记录可能的异常的最佳方法是什么？

如何使用Python的文档字符串记录带参数的方法？

编辑: PEP 257给出了这个例子:

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
    ...

这是大多数Python开发人员使用的约定吗？

Keyword arguments:
<parameter name> -- Definition (default value if any)

我期待一些更正式的东西,比如

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

    @param: real The real part (default 0.0)
    @param: imag The imaginary part (default 0.0)

    """
    if imag == 0.0 and real …