변수의 독 스트링

변수의 독 스트링

---

일반 변수에 독 스트링을 사용할 수 있습니까? 예를 들어 다음과 같은 모듈이 있습니다.t

def f():
    """f"""

l = lambda x: x
"""l"""

그리고 나는

>>> import t
>>> t.f.__doc__
'f'

그러나

>>> t.l.__doc__
>>> 

예는 PEP 258 과 유사합니다 ( "this is g"검색).

---

아니요, 가능하지 않으며 가능하다면 유용하지 않을 것입니다.

독 스트링은 항상 객체 (모듈, 클래스 또는 함수)의 속성이며 특정 변수에 연결되지 않습니다.

즉, 다음 을 수행 할 수 있습니다.

t = 42
t.__doc__ = "something"  # this raises AttributeError: '__doc__' is read-only

변수가 아닌 정수 42에 대한 설명서를 설정합니다 t. 리 바인드하자마자 독 스트링 t을 잃게됩니다. 문자열 수와 같은 변경 불가능한 객체는 때때로 서로 다른 사용자간에 공유되는 단일 객체를 가지므로이 예제에서는 실제로 42프로그램 전체의 모든 발생에 대해 독 스트링을 설정했을 것입니다 .

print(42 .__doc__) # would print "something" if the above worked!

변경 가능한 객체의 경우 반드시 유해하지는 않지만 객체를 리 바인드하면 여전히 제한적으로 사용됩니다.

클래스의 속성을 문서화하려면 클래스의 독 스트링을 사용하여 설명하십시오.

---

Epydoc은 변수에 대한 독 스트링을 허용 합니다 .

언어가 직접 제공하지는 않지만 Epydoc은 변수 독 스트링을 지원합니다. 변수 할당 문 바로 뒤에 베어 문자열 리터럴이 오면 해당 할당은 해당 변수에 대한 독 스트링으로 처리됩니다.

예:

class A:
    x = 22
    """Docstring for class variable A.x"""

    def __init__(self, a):
        self.y = a
        """Docstring for instance variable A.y

---

일부 Python 문서 스크립트에는 var를 문서화하기 위해 모듈 / 클래스 독 스트링에서 사용할 수있는 표기법이 있습니다.

예를 들어 spinx의 경우 : var 및 : ivar를 사용할 수 있습니다. 이 문서를 참조하십시오 (약 절반 정도).

---

글쎄, 파이썬은 전역 정의 바로 뒤에 정의 된 문자열을 변수에 대한 독 스트링으로 취급하지 않더라도 스핑크스는 그렇게하고 그것을 포함하는 것은 확실히 나쁜 습관이 아닙니다.

debug = False
'''Set to True to turn on debugging mode. This enables opening IPython on 
exceptions.
'''

다음은 모듈을 스캔하고 전역 변수 정의 이름, 값 및 뒤에 오는 독 스트링을 가져 오는 코드입니다.

def GetVarDocs(fname):
    '''Read the module referenced in fname (often <module>.__file__) and return a
    dict with global variables, their value and the "docstring" that follows
    the definition of the variable
    '''
    import ast,os
    fname = os.path.splitext(fname)[0]+'.py' # convert .pyc to .py
    with open(fname, 'r') as f:
        fstr = f.read()
    d = {}
    key = None
    for node in ast.walk(ast.parse(fstr)):
        if isinstance(node,ast.Assign):
            key = node.targets[0].id
            d[key] = [node.value.id,'']
            continue
        elif isinstance(node,ast.Expr) and key:
            d[key][1] = node.value.s.strip()
        key = None
    return d

---

아니요, 내가 아는 한 모듈, (람다 및 "일반") 함수 및 클래스에 대해서만이 작업을 수행 할 수 있습니다. 다른 객체, 심지어 변경 가능한 객체라도 해당 클래스의 독 스트링을 상속하고 AttributeError변경하려고하면 발생합니다.

>>> a = {}
>>> a.__doc__ = "hello"
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'dict' object attribute '__doc__' is read-only

(두 번째 예제는 유효한 Python이지만 문자열 """l"""은 아무 작업도하지 않습니다. 생성, 평가 및 폐기됩니다.)

---

Sphinx에는 속성을 문서화하기위한 내장 구문이 있습니다 (예 : @duncan이 설명하는 값이 아님). 예 :

#: This is module attribute
x = 42

class MyClass:

    #: This is a class attribute
    y = 43

You can read more in the Sphinx docs: http://www.sphinx-doc.org/en/1.4.8/ext/autodoc.html#directive-autoattribute

...or in this other question: How to document a module constant in Python?

---

To add to to ford's answer about Epydoc, note that PyCharm will also use a string literal as the documentation for a variable in a class:

class Fields_Obj:
    DefaultValue=None
    """Get/set the default value of the data field"""

ReferenceURL : https://stackoverflow.com/questions/8820276/docstring-for-variable