如何使用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 …如何告诉JSDoc有关返回的对象的结构.我找到了@return {{field1: type, field2: type, ...}} description语法并试了一下:
/**
* Returns a coordinate from a given mouse or touch event
* @param {TouchEvent|MouseEvent|jQuery.Event} e
* A valid mouse or touch event or a jQuery event wrapping such an
* event.
* @param {string} [type="page"]
* A string representing the type of location that should be
* returned. Can be either "page", "client" or "screen".
* @return {{x: Number, y: Number}}
* The location of the event
*/
var getEventLocation …javascript documentation-generation code-documentation jsdoc jsdoc3
我需要为我的工作场所实施文档生成解决方案,并将其缩小到标题中提到的三个.我已经能够在这些解决方案之间进行正式比较的方式中找到很少的信息,我希望那些在上述一个或多个方面有经验的人可以权衡:
以下是我从初次传球中收集到的内容:
HeaderDoc优点:与苹果公司现有的文档一致,与制作苹果文档集的兼容性
HeaderDoc缺点:难以修改行为,项目没有积极处理,许多人已经转离它(意味着必须有一些不足之处,尽管我无法量化它).
Doxygen Pros:活跃支持社区b/c广泛使用基础,非常可定制,大多数输出类型(如乳胶等)
Doxygen缺点:工作使其外观/行为与apple docs一致,与apple docsets的兼容性并不那么简单
AppleDoc专业人士:看起来与苹果现有的文档一致,与制作苹果文档集的兼容性,
AppleDoc缺点:有关typedef,枚举和函数文档的问题,正在积极开发中
这听起来准确吗？我们理想的解决方案将:
根据以上所有信息,上述任何一种解决方案明显优于其他解决方案吗？任何建议或信息,将非常感激.
我正在尝试从我的模块中创建一个文档.我pydoc在Windows 7中使用Python 3.2.3从命令行使用:
python "<path_to_pydoc_>\pydoc.py" -w myModule
这导致我的shell充满了文本,我的模块中的每个文件都有一行,说:
no Python documentation found for '<file_name>'
这就像Pydoc试图获取我的文件的文档,但我想自动创建它.我找不到使用谷歌的好教程.有没有人有关于如何使用Pydoc的任何提示？
如果我尝试使用一个文件创建文档
python ... -w myModule\myFile.py
此外,它在我的计算机上有一个指向文件本身的链接,我可以单击它,它会在我的网络浏览器上显示文件内部的内容.
python documentation documentation-generation pydoc python-3.x
是否有任何工具可以为TypeScript源代码生成文档？或者我应该使用像NaturalDocs这样的通用名称？块注释/用于独立文档量的建议样式是什么？
我应该使用:
///<foo>bar</foo> MSVS kind of comments?
要么
/** @javadoc style comments */
也许
/*
Something like this?
*/
我害怕使用,///因为它用于进口,我不想继续以类似的方式介绍其他未来的功能 - 但你永远不知道......
或者是否可以从TypeScript生成文档化的JavaScript,然后使用JavaScript工具链？
是否可以在roxygen过程中将.R文件包含在我的包的数据目录中？
我在数据目录中放了几个.R文件.当它们使用data()获取时,它们会读入原始数据文件并执行一些转换.
我正在尝试使用Sphinx为我的代码库自动生成基本文档.但是,我很难指示Sphinx递归扫描我的文件.
我有一个Python代码库,其文件夹结构如下:
<workspace>
src
mypackage
__init__.py
subpackageA
__init__.py
submoduleA1
submoduleA2
subpackageB
__init__.py
submoduleB1
submoduleB2
我运行了sphinx-quickstart <workspace>,所以现在我的结构看起来像:
<workspace>
src
mypackage
__init__.py
subpackageA
__init__.py
submoduleA1
submoduleA2
subpackageB
__init__.py
submoduleB1
submoduleB2
index.rst
_build
_static
_templates
我已经阅读了快速入门教程http://sphinx.pocoo.org/tutorial.html,虽然我仍在尝试理解文档,但它的措辞让我担心Sphinx会假设我要手动创建我的代码库中每个模块/类/函数的文档文件.
但是,我确实注意到了"automodule"语句,并且我在快速入门期间启用了autodoc,所以我希望大多数文档都可以自动生成.我修改了我的conf.py来将我的src文件夹添加到sys.path然后修改我的index.rst以使用自动模块.所以现在我的index.rst看起来像:
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. automodule:: alphabuyer
:members:
我在子包中定义了几十个类和函数.然而,当我跑:
sphinx-build -b html . ./_build
它报道:
updating environment: 1 added, 0 changed, 0 removed
这似乎无法导入我的包内的任何东西.查看生成的index.html在"Contents:"旁边没有显示任何内容.索引页面仅显示"mypackage(模块)",但单击它显示它也没有内容.
如何指导Sphinx递归解析包并自动生成它遇到的每个类/方法/函数的文档,而不必自己手动列出每个类？
我正在开发一个项目,其中c ++/cli库主要来自ac#application.
有没有办法让c ++/cli中的代码注释在visual studio中对c#intellisence可见？
假设没有,那么记录c ++/cli代码的最佳方法是什么,以便从c#中更容易使用(当然在c ++/cli中)？您对XML评论vs doxygen与其他工具(哪些)的看法是什么？
有没有人知道使用.proto源文件生成Google Protobuf文档的好工具？
documentation protocols documentation-generation protocol-buffers