Python中的多行注释文档编写风格汇总

作者:mattkang 时间:2023-05-05 02:41:18 

什么是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:

敲make html命令,就可以从docstring中生成相关的文档了,不用多手写一遍rst.
看效果:

Python中的多行注释文档编写风格汇总

标签:Python,注释
0
投稿

猜你喜欢

  • 细数JavaScript 一个等号,两个等号,三个等号的区别

    2023-08-25 08:22:09
  • 一文详解Python中的Map,Filter和Reduce函数

    2022-03-02 07:51:28
  • 解决vue 给window添加和移除resize事件遇到的坑

    2024-04-10 13:45:45
  • 利用python爬取散文网的文章实例教程

    2023-06-17 10:40:18
  • 详解php中implode explode serialize json msgpack性能对比

    2023-09-03 18:00:19
  • MySQL表设计优化与索引 (四)

    2010-10-25 19:50:00
  • 使用python爬取taptap网站游戏截图的步骤

    2021-09-17 07:44:34
  • vue父子组件的互相传值和调用

    2024-04-09 10:47:51
  • python内存管理分析

    2022-04-16 22:03:03
  • 使用正则表达式匹配tsql注释语句

    2024-01-18 16:42:50
  • selenium+python实现基本自动化测试的示例代码

    2023-12-10 00:17:07
  • 简单介绍Python中的filter和lambda函数的使用

    2023-05-30 18:18:36
  • PyCharm 常用快捷键和设置方法

    2022-04-09 01:40:59
  • python+logging+yaml实现日志分割

    2023-12-18 01:19:08
  • python爬虫爬取股票的k线图

    2021-06-30 15:54:37
  • 使用Keras加载含有自定义层或函数的模型操作

    2022-12-25 19:29:29
  • Python基础之hashlib模块subprocess模块logging模块

    2022-08-12 02:45:52
  • Mysql导入TXT文件

    2012-01-05 19:01:10
  • python Spyder界面无法打开的解决方法

    2023-03-02 09:12:09
  • 微信小程序列表渲染功能之列表下拉刷新及上拉加载的实现方法分析

    2024-05-11 09:34:44
  • asp之家 网络编程 m.aspxhome.com