Pythonのdocstringとは何ですか
そして、Javaに似た、Pythonはまた、コメントフォームのドキュメンテーション文字列を介して、プログラム、クラス、関数などの文書を作成します。人々のためだけでなく、ドキュメンテーション文字列内で作成した文書、読みやすくするだけでなく、私たちはより良いプログラムを理解するために、いくつかの制限の関数、クラス、変数などを使用して、このような自動認識などのIDEツールを可能にします。
3つのスタイルのPythonのドキュメンテーション文字列
一般的には、Pythonのドキュメンテーション文字列は、3つの主要なスタイル、すなわちreSTのスタイルは、Googleのスタイルとnumpyのスタイルがあります。
reSTのスタイル
残りは立っreStructredTextを。クラスを説明し、いくつかの重要なパラメータのコロンの冒頭では、関数は値、およびその他の異常を返します。
たとえば、私たちは新しい作成し、ホイールの二重リンクリストを構築したいDoubleLinkList.pyファイルを。これは、クラスは、ノードの二重リンクリストである、2つのクラスが含まれDLLNode、二重リンクリストのタイプですDoubleLinkList。
まず、見てDLLNodeクラス。
class DLLNode(object):
"""
The definition of node of double link list.
:param val: The value of a node.
:param prev: The pointer of the previous node of this node.
:param next: The pointer of the next node of this node.
:type val: Any
:type prev: DLLNode, default None
:type next: DLLNode, default None
"""
def __init__(self, val, prev=None, next=None):
self.val = val
self.prev = prev
self.next = next私たちはで見ることができるDLLNode引用符の3組でクラス"""DLLNodeクラスのドキュメンテーション文字列を確立しました。注ドキュメンテーション文字列は、他のコードの先頭に配置する必要があります。マーキング次の文と共通のクラスのドキュメンテーション文字列で：
:param <类属性名称>: <描述>
:type <类属性名称>: <类型>前記のような基本的なタイプのタイプに加えてint、float、strなど、また、リストタイプであってもよいList[type]、タプルTuple[types]、辞書、Dict[KeyType, ValueType]等、また、種々のモジュールで定義されたタイプのものであってもよいです。自身の異なるタイプはPythonの種類が付属していたときに、リストや辞書のタプルであることに注意してください。
ここでは、する必要はありませんDLLNodeで入力__init__()ドキュメンテーション文字列関数を追加します。ドキュメントを生成するとき、クラスのPythonのドキュメンテーション文字列は自動的ににコピーされ__init__()機能。
ここを見ていDoubleLinkListたクラス。
class DoubleLinkList(object):
"""
The definition of double link list.
:param head: The head pointer of the list.
:type head: DLLNode
"""
def __init__(self, head):
self.head = head
def insert_node(self, val, node):
"""
Insert a node before the node which data is val.
:param val: The value to be find to insert a node before it.
:param node: The node ready to insert.
:type val: Any
:type node: DLLNode
"""
pass
def remove_node(self, val):
"""
Remove a node which data is val.
:param val: The val of node to be removed.
"""
pass
def length(self):
"""
Returns the length of this link table.
:return: The length of this link table.
:rtype: int
"""
pass
def search_node(self, val):
"""
Search the first position of node which data equals val.
:param val: The value to be searched.
:return: The position of val first appeared.
:rtype: int
"""
pass
def update_node(self, position, val):
"""
Update the node in position by val.
:param position: The position of the node to be updated.
:param val: The target value of updated node.
:type position: int
:type val: Any
"""
pass我々が与えたと仮定しDoubleLinkListたクラスの設計要件と長CRUDの5つの方法を。私たちは、に加えて、それを見ることができます:paramし、:type外部に、以下に記載されているいくつかの新しいタグがあります。
:return: <对返回值的描述>
:rtype: <返回值类型>
:raises: <可能抛出的异常列表>私たちはドキュメンテーション文字列に関数を指定する場合:paramや:type、後で関数を呼び出すときに、関数へのパラメータの間違った種類を通過した場合、IDEは、警告、我々は正しいパラメータ型を渡すリマインダーを発行します。
Googleのスタイル
reSTのスタイルに加えて、Googleのスタイルのドキュメンテーション文字列も共通の仕様です。
それでも上記DoubleLinkListの例。Googleのスタイルのドキュメント文字列は次のよう：
class DLLNode(object):
"""
The definition of node of double link list.
Args:
val (Any): The value of Node.
prev (DLLNode): The previous node of this node.
next (DLLNode): The next node of this node.
"""
def __init__(self, val, prev=None, next=None):
self.val = val
self.prev = prev
self.next = next
class DoubleLinkList(object):
"""
The definition of double link list.
Args:
head (DLLNode): The head pointer of the link list.
"""
def __init__(self, head):
self.head = head
def insert_node(self, val, node):
"""
Insert a node before the node which data is val.
Args:
val (Any): The value to be find to insert a node before it.
node (DLLNode): The node ready to insert.
"""
pass
def remove_node(self, val):
"""
Remove a node which data is val.
Args:
val (DLLNode): The val of node to be removed.
"""
pass
def length(self):
"""
Returns the length of this link table.
Returns:
int: The length of this link list.
"""
pass
def search_node(self, val):
"""
Search the first position of node which data equals val.
Args:
val: The value to be searched.
Returns:
int: The first position of the searched value.
"""
pass
def update_node(self, position, val):
"""
Update the node in position by val.
Args:
position (int): The position of node to be updated.
val: The new value of target.
"""
pass
さまざまなスタイル、Googleのスタイルが書かれたすべてのパラメータを指定して、残りArgsのラベルの下で、およびに書かれたすべての戻り値Returnsのラベル。私は個人的にはreSTスタイルよりも、Googleのスタイルより読みやすくと思います。でArgsラベル、パラメータの名前の後に添加することができる(类型)パラメータの種類を決定するために、また、パラメータの種類に制限効果を再生することができます。
numpyのスタイル
numpyの行列が解析され、科学的なコンピューティング、一般的なPythonライブラリは、機械学習に使用されます。一つの詳細かつ完全な文書だけでなく、モデルを学習プログラマ。numpyのは、また、Pythonのドキュメンテーション文字列の独自のスタイルを持っています。我々はまだDoubleLinkList説明するための一例としてモジュール。
class DLLNode(object):
"""
The definition of node of double link list.
Parameters
----------
val : Any
The value of node.
prev : DLLNode
The previous node of this node.
next : DLLNode
The next node of this node.
Attributes
----------
val : Any
The value of node.
prev : DLLNode
The previous node of this node.
next : DLLNode
The next node of this node.
"""
def __init__(self, val, prev=None, next=None):
self.val = val
self.prev = prev
self.next = next
class DoubleLinkList(object):
"""
The definition of double link list.
Parameters
----------
head : DLLNode
The head pointer of the link list.
Attributes
----------
head : DLLNode
The head pointer of the link list.
"""
def __init__(self, head):
self.head = head
def insert_node(self, val, node):
"""
Insert a node before the node which data is val.
Parameters
----------
val:
The value to be find to insert a node before it.
node : DLLNode
The node ready to insert.
"""
pass
def remove_node(self, val):
"""
Remove a node which data is val.
Parameters
----------
val :
The val of node to be removed.
"""
pass
def length(self):
"""
Returns the length of this link table.
Returns
-------
int
The length of this link list.
"""
pass
def search_node(self, val):
"""
Search the first position of node which data equals val.
Parameters
----------
val:
The value to be searched.
Returns
-------
int
The first position of the searched value.
"""
pass
def update_node(self, position, val):
"""
Update the node in position by val.
Parameters
----------
position :int
The position of node to be updated.
val:
The new value of target.
"""
pass
別のGoogleスタイル、クラスを記述するためにnumpyのスタイル次の形式：
"""
类描述
Parameters
----------
参数 : [类型]
参数的描述
Attributes
----------
属性 : [类型]
属性的描述
"""パラメータと異なる場合があります属性。具体的な違いは、私はかなり理解していないです。
以下に説明する機能
"""
函数描述
Parameters
----------
参数 : [类型]
参数的描述
Returns
-------
类型
返回值的描述
Raises
------
异常名称
异常描述
Examples
--------
范例描述
Yields(仅针对生成器函数)
------
类型
生成器返回值描述
Note
----
注释内容
"""numpyのスタイルのドキュメンテーション文字列は、スフィンクスを持つドキュメントのHTMLフォームを生成していないよう。
概要
この記事では、私が個人的にGoogleのスタイルのコントラストが最高の一つである、両方のスフィンクスは、HTML形式のドキュメントを生成するには、コマンドラインから直接使用、またはことができると考えている、Pythonでプログラミングの3つの一般的なドキュメンテーション文字列のスタイルを記述するヘルプ機能を通じて、より読みやすい文書を取得します。しかしPycharmなIDEとして、デフォルトのreSTスタイルによってサポートされています。どのように使用し、あなたの好みやプロジェクトの要件によって異なります。