Python中的多行注释文档编写风格汇总
什么是docstring
在软件工程中，其实编码所占的部分是非常小的，大多是其它的事情，比如写文档。文档是沟通的工具。
在Python中，比较推崇在代码中写文档，代码即文档，比较方便，容易维护，直观，一致。
代码写完，文档也出来了。其实Markdown也差不多这种思想，文本写完，排版也完成了。
看看PEP 0257中对docstring的定义：
A docstring is a string literal that occurs as the first statement in
a module, function, class, or method definition. Such a docstring
becomes the __doc__ special attribute of that object.
简单来说，就是出现在模块、函数、类、方法里第一个语句的，就是docstring。会自动变成属性__doc__。
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生成一个patch，然后打patch。
$ pyment test.py #生成patch $ patch -p1 < test.py.patch #打patch
详情：https://github.com/dadadel/pyment
使用sphinx的autodoc自动从docstring生产api文档，不用再手写一遍
我在代码中已经写过docstring了，写api文档的内容跟这个差不多，难道要一个一个拷贝过去rst吗？当然不用。sphinx有autodoc功能。
首先编辑conf.py文件，
1. 要有'sphinx.ext.autodoc'这个extensions
2. 确保需要自动生成文档的模块可被import，即在路径中。比如可能需要sys.path.insert(0, os.path.abspath(‘../..'))
然后，编写rst文件，
xxx_api module --------------------- .. automodule:: xxx_api :members: :undoc-members: :show-inheritance:
看效果：
相关文章
这篇文章主要为大家介绍了Python装饰器类方法扩展元类管理实例探究,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪2024-01-01
这篇文章主要给大家介绍了关于django中forms组件的使用与注意的相关资料，文中通过示例代码介绍的非常详细，对大家学习或者使用django具有一定的参考学习价值，需要的朋友们下面来一起学习学习吧2019-07-07
PyCharm 是 JetBrains 开发的一款 Python 跨平台编辑器,下面这篇文章主要介绍了Pycharm连接远程服务器并远程调试的全过程,文中通过图文介绍的非常详细,需要的朋友可以参考下2021-06-06
这篇文章主要为大家介绍了Python类和对象，具有一定的参考价值，感兴趣的小伙伴们可以参考一下，希望能够给你带来帮助2021-12-12
正则表达式广泛用于与文字、字符串的格式化,放到Python里使用,再合适不过.尤其是在编写爬虫时,用正则表达式匹配URL、匹配IP等,正则表达式都是一个简单、高效的选择,需要的朋友可以参考下2021-06-06
python利用urllib和urllib2访问http的GET/POST详解
urllib模块提供的上层接口,使我们可以像读取本地文件一样读取www和ftp上的数据。下面这篇文章主要给大家介绍了关于python如何利用urllib和urllib2访问http的GET/POST的相关资料，需要的朋友可以参考借鉴，下面来一起看看吧。2017-09-09
这篇文章主要为大家介绍了基于Python如何实现评论区抽奖的功能，文章的示例代码讲解详细，对我们学习Python有一定帮助，需要的朋友可以学习一下2021-12-12
在本篇文章里小编给各位分享了关于python怎么实现键盘输入的图文步骤以及相关知识点内容，需要的朋友们参考下。2019-07-07
JSON(JavaScript Object Notation)是一种轻量级的数据交换格式,下面这篇文章主要给大家介绍了关于使用python解析json字段的3种方式,文中通过实例代码介绍的非常详细,需要的朋友可以参考下2022-07-07
这篇文章主要为大家详细介绍了python如何在终端里面显示一张图片的方法，感兴趣的小伙伴们可以参考一下2016-08-08
最新评论