파이썬에서 help 메소드로 함수 설명 보기, 함수의 문서화란?

파이썬 help 사용법, 함수 문서화 방법

이번 글에서는 파이썬에서 특정 함수 및 클래스에 대한 도움말 및 사용법을 확인하고 싶은 경우

유용하게 활용이 가능한 help 메소드에 대한 개요를 다루어보고,

이와 관련되어 직접 정의한 함수 혹은 클래스에 대한 설명서를 작성하는

'함수의 문서화'라는 개념에 대해서도 살펴보도록 하겠습니다.

 

 

help로 클래스 및 함수에 대한 설명을 확인하는 방법

help(클래스 이름) 혹은 help(함수 이름)의 형태로

파이썬에서 클래스나 함수에 대한 도움말을 쉽게 볼 수 있습니다.

 

파이썬 내장 함수 중 하나인 range는 사실 클래스로 구현이 되어있는데,

클래스 설명글에 대한 예시로 이 range class에 대한 설명 글을 살펴보도록 하겠습니다.

실제로는 위 사진에서 잘린 내용의 뒷 부분에도 문서가 굉장히 길게 작성이 되어있는데,

range의 기본 동작 원리 및 관련 내부 메소드들에 대한 내용 확인이 가능함을 보았습니다.

 

이번에는 클래스가 아닌 단일 함수에 help를 적용한 경우로

random 모듈 내의 random 함수에 대한 설명서를 보겠습니다.

import random

help(random.random)

'''
Help on built-in function random:

random(...) method of random.Random instance
    random() -> x in the interval [0, 1).'''

꽤나 간단한 함수인만큼 간략하게 작성된 설명서를 확인할 수 있었습니다.

반응형

함수/클래스 설명 달기 방법(함수의 문서화)

그렇다면, 직접 정의한 함수 혹은 클래스에 대해서 help 메소드를 실행한 결과를

원하는대로 작성하기 위해서는 어떻게 해야할까요?

 

이는 함수 및 클래스의 시작 부분에 문자열로 구성된 주석을 넣어주시면

help 메소드 실행결과로 해당 문자열이 출력되는 원리가 적용되고,

함수(클래스)에 설명서를 보여줄 수 있게 됩니다. 이 과정을 '함수의 문서화'라고도 합니다.

 

먼저 직접 정의한 함수에 도움말을 첨부한 예시를 보여드리겠습니다.

def my_func(a, b):
    ''' a, b 두 숫자를 입력으로 받아
    a * b + 2를 반환하는 함수입니다.'''
    return a * b + 2

my_func(3, 5) # 17

help(my_func)

'''
Help on function my_func in module __main__:

my_func(a, b)
    a, b 두 숫자를 입력으로 받아
    a * b + 2를 반환하는 함수입니다.
'''

help 출력 결과, 함수의 앞 부분에서 적은 설명글이 출력된 것을 확인 가능합니다.

 

이번에는 클래스 및 클래스 내부 함수에 대해서 설명서를 작성한 예시입니다.

class my_class():
    '''클래스 설명글입니다.'''

    def __init__():
        '''클래스 초기화 부분입니다.'''
        pass

    def class_func():
        '''클래스 내부 함수 설명글입니다.'''
        pass

클래스 앞 부분의 설명 및 각 내부 메소드 내의 설명 부분도 잘 출력된 것을 볼 수 있었습니다.