파이썬 PEP-8 반환 값 형식화

Question

구체적인 답을 보지 못했습니다.하지만 파이썬 문서 문자열의 반환 값에 대한 스타일 규칙에 관한 질문이 있습니다.

def foo(ex): 
    """ 
    Sample text.... 
    :param ex: description... 
    :return: description of return value 
    """ 
    output = 2*ex 
    return output 

내 질문이 있는지 여부 그래야 이름은 :이 기능에 대한 문서화 문자열을 만든 경우처럼

PyCharm에서

def foo(ex): 
    output = 2*ex 
    return output 

,이 보일 것이다

는 함수처럼 고려 docstring에 반환 값이 있습니까? 즉

: 리턴 : 리턴 값의 설명

: 리턴 : 출력 : 리턴 값

의 설명이을위한 코딩 표준이 있는가 또는 대부분 개인적인 취향에 남아 ?

Answer 1

문서화 문자열 규칙은 실제로 PEP-257에 정의되어 있습니다 (그리고 PEP-8는 단지 그것을 참조)하지만 일반 서식, 만족하지 덮여있다.

문서화 문자열의 내용은 일반적으로 Sphinx라는 파이썬 문서 생성기에 의해 해석되고, 스핑크스에, 다음 info fields이 존재 :

• param, parameter, arg, argument, key, keyword : 설명 매개 변수의.
• type : 매개 변수의 유형. 가능한 경우 링크를 만듭니다.
• raises, raise, except, exception : 특정 예외가 발생했습니다.
• var, ivar, cvar : 변수에 대한 설명.
• vartype : 변수 유형입니다. 가능한 경우 링크를 만듭니다.
• returns, return : 반환 값에 대한 설명.
• rtype : 반환 유형 가능한 경우 링크를 만듭니다.

을 주목 반환 형식에 대한 rtype.

따라서 rtype으로 반환 유형을 지정할 수 있지만 개체 반환의 실제 (로컬) 이름은 부적합합니다.

def foo(x): 
    """Sample text. 
    :param x: parameter description 
    :type x: int 
    :return: description of return value 
    :rtype: int 
    """ 
    output = 2*ex 
    return output 

Answer 2

이미 randomir로 언급했듯이, Python PEP는 문서화 문자열의 내용을 구성하는 방법을 지정하지 않습니다. 그러나 큰 코딩 프로젝트는 보통 docstring 컨텐트에 대한 독자적인 가이드 라인을 가지고 있으며, 그 중 하나를 적용 할 수 있습니다.

개인적으로 나는 Numpy 문서 형식 (here 및 here 참조)을 좋아합니다. 리턴 값의 지역 이름은 Numpy 스타일의 문서화 문자열에 포함되지 않습니다. 함수에 대한 참조 문은 다음과 같이 보일 것이다 :

def foo(ex): 
    """One-line function description. 

    Parameters 
    ---------- 
    ex : float 
     Description of parameter. 

    Returns 
    ------- 
    float 
     Description of return value. 

    """ 
    output = 2*ex 
    return output 

NumPy와 스타일의 문서화 문자열뿐만 아니라 Sphinx 문서 생성기에 의해 지원됩니다.