总结下python文件的文档写法，虽然针对是python的，但对大部分语言也都通用。

文档有两方面的好处，一是可以帮助阅读代码，大部分IDE在预览函数/类时都会将其文档也实时加载出来；二是后期可以方便导出成整体的文档文件，便于用户查阅。

函数文档

  • 这部分没有固定的格式，通常只需写明：description、params和return值三部分信息即可。
  • 因为格式比较简单，因此也没必要使用插件，直接自己随手写了就ok。写在函数下面，这样IDE预览函数的时候就可以直接访问到文档了。
  • 格式参考如下：
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    def fn(param1, param2):
        """Description here.
        
        Params:
            param1(int):
            param2(int):
        
        Returns:
            bool: The return value.

        """

类文档

直接在类下面写类的描述信息即可，关于类的property和method的文档直接写在其下面即可。

1
2
3
4
5
6
7
8
9
class MyClass():

@property
def some_property(self):
    """This is the property description"""
    return xxx

def some_method(self, param1):
    """"function document(see above section)"""

文件头文档

直接在文件头写相应的描述信息即可。

1
2
3
4
"""BERT finetuning runner."""

import tensorflow as ts
import numpy as np

Post Date： 2019-07-24

版权声明： 本文为原创文章，转载请注明出处