Python中的多行注释文档编写风格汇总
什么是docstring 在软件工程中,其实编码所占的部分是非常小的,大多是其它的事情,比如写文档。文档是沟通的工具。 A docstring is a string literal that occurs as the first statement in def foo(): """ This is function foo""" 可通过foo.__doc__访问得到' This is function foo'. 各类docstring风格: Epytext 这是曾经比较流行的一直类似于javadoc的风格。 """ This is a javadoc style. @param param1: this is a first param @param param2: this is a second param @return: this is a description of what is returned @raise keyError: raises an exception """ reST 这是现在流行的一种风格,reST风格,Sphinx的御用格式。我个人也是喜欢用这种风格,比较紧凑。 """ This is a reST style. :param param1: this is a first param :param param2: this is a second param :returns: this is a description of what is returned :raises keyError: raises an exception """ Google风格 """ This is a groups style docs. Parameters: param1 - this is the first param param2 - this is a second param Returns: This is a description of what is returned Raises: KeyError - raises an exception """ Numpydoc (Numpy风格) """ My numpydoc description of a kind of very exhautive numpydoc format docstring. Parameters ---------- first : array_like the 1st param name `first` second : the 2nd param third : {'value','other'},optional the 3rd param,by default 'value' Returns ------- string a value in a string Raises ------ KeyError when a key error OtherError when an other error """ docstring工具之第三方库pyment 用来创建和转换docstring. $ pyment test.py #生成patch $ patch -p1 < test.py.patch #打patch 详情:https://github.com/dadadel/pyment 使用sphinx的autodoc自动从docstring生产api文档,不用再手写一遍 我在代码中已经写过docstring了,写api文档的内容跟这个差不多,难道要一个一个拷贝过去rst吗?当然不用。sphinx有autodoc功能。 然后,编写rst文件, xxx_api module --------------------- .. automodule:: xxx_api :members: :undoc-members: :show-inheritance: 敲make html命令,就可以从docstring中生成相关的文档了,不用多手写一遍rst.
看效果: (编辑:李大同) 【声明】本站内容均来自网络,其相关言论仅代表作者个人观点,不代表本站立场。若无意侵犯到您的权利,请及时与联系站长删除相关内容! |