# Python docstring

By [Primrose](https://paragraph.com/@primrose) · 2022-10-06

---

What is docstring?
------------------

*   class, module, function, method 정의 시 사용되는 python documentation string
    
*   python 객체의 \__doc_\_ attribute 또는 help() function을 통해 접근할 수 있다.
    
*   개발된 기능을 사용하거나 개발에 기여하는 다른 개발자들의 이해를 돕기 위해 작성되는 주석
    
*   class, module, function, method의 첫 줄에 위치한다.
    
*   예시: pandas
    

![help(pandas)](https://storage.googleapis.com/papyrus_images/c58ca7309dc928d46d3e9a50e338cf4ecb7f3b07700db887b641cd5ff4ac5ef9.png)

help(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

---

*Originally published on [Primrose](https://paragraph.com/@primrose/python-docstring)*