class, module, function, method 정의 시 사용되는 python documentation string
python 객체의 _doc_ attribute 또는 help() function을 통해 접근할 수 있다.
개발된 기능을 사용하거나 개발에 기여하는 다른 개발자들의 이해를 돕기 위해 작성되는 주석
class, module, function, method의 첫 줄에 위치한다.
예시: pandas
Formats of docstring
One line docstring
def square(a):
'''Returned argument a is squared.'''
return a**a
Multi line docstring
class Vehicle(object):
'''
The Vehicle object contains lots of vehicles
:param arg: The arg is used for ...
:type arg: str
:param `*args`: The variable arguments are used for ...
:param `**kwargs`: The variable arguments are used for ...
:ivar arg: This is where we store arg
:vartype arg: str
'''
def __init__(self, arg, *args, **kwargs):
self.arg = arg
def cars(self, distance, destination):
'''
We can't travel a certain distance in vehicles without fuels, so here's the fuels
:param distance: The amount of distance traveled
:type amount: int
:param bool destinationReached: Should the fuels be refilled to cover required distance?
:raises: :class:`RuntimeError`: Out of fuel
:returns: A Car mileage
:rtype: Cars
'''
pass
roles
param: 필수적으로 명시해야 한다.
type: sphinx data type for param
return: returned object
rtype: type of object retured
Google style
class Vehicles(object):
'''
The Vehicle object contains a lot of vehicles
Args:
arg (str): The arg is used for...
*args: The variable arguments are used for...
**kwargs: The keyword arguments are used for...
Attributes:
arg (str): This is where we store arg,
'''
def __init__(self, arg, *args, **kwargs):
self.arg = arg
def cars(self, distance, destination):
'''We can't travel distance in vehicles without fuels, so here is the fuels
Args:
distance (int): The amount of distance traveled
destination (bool): Should the fuels refilled to cover the distance?
Raises:
RuntimeError: Out of fuel
Returns:
cars: A car mileage
'''
pass
Numpy Style
class Vehicles(object):
'''
The Vehicles object contains lots of vehicles
Parameters
----------
arg : str
The arg is used for ...
*args
The variable arguments are used for ...
**kwargs
The keyword arguments are used for ...
Attributes
----------
arg : str
This is where we store arg,
'''
def __init__(self, arg, *args, **kwargs):
self.arg = arg
def cars(self, distance, destination):
'''We can't travel distance in vehicles without fuels, so here is the fuels
Parameters
----------
distance : int
The amount of distance traveled
destination : bool
Should the fuels refilled to cover the distance?
Raises
------
RuntimeError
Out of fuel
Returns
-------
cars
A car mileage
'''
pass
