Docstring - Docstring

În programare , un docstring este un șir literal specificat în codul sursă care este utilizat, ca un comentariu , pentru a documenta un anumit segment de cod. Spre deosebire de comentariile convenționale ale codului sursă sau chiar comentariile formatate în mod specific, cum ar fi documentația Javadoc , șirurile de documente nu sunt scoase din arborele sursă atunci când este analizat și sunt păstrate pe tot parcursul programului. Acest lucru permite programatorului să inspecteze aceste comentarii în timpul rulării, de exemplu ca sistem de ajutor interactiv sau ca metadate .

Se pare că a fost introdus pentru prima dată în implementarea inițială TECO a Emacs .

Limbile care acceptă docstrings includ Python , Lisp , Elixir , Clojure , Gherkin , Julia și Haskell .

Exemple de implementare

Elixir

Documentarea este acceptată la nivel de limbă, sub formă de șiruri de documente. Markdown este limbajul de marcare de facto al Elixir pentru alegere în docstrings: 

def module MyModule do
  @moduledoc """
  Documentation for my module. With **formatting**.
  """

  @doc "Hello"
  def world do
    "World"
  end
end

Lisp

În Lisp, șirurile de documente sunt cunoscute sub numele de șiruri de documentare. Standardul Common Lisp afirmă că o anumită implementare poate alege să arunce docstringurile oricând doresc, din orice motiv. Când sunt păstrate, șirurile de documente pot fi vizualizate și modificate folosind funcția DOCUMENTARE. De exemplu: 

 (defun foo () "hi there" nil)
 (documentation #'foo 'function) => "hi there"

Piton

Practica obișnuită de a documenta un obiect de cod în capul definiției sale este surprinsă de adăugarea sintaxei docstring în limbajul Python.

Șirul de documente pentru un obiect de cod Python (un modul, o clasă sau o funcție) este prima afirmație a acelui obiect de cod, imediat după definiție (declarația „def” sau „clasă”). Declarația trebuie să fie un șir literal, nu orice alt tip de expresie. Șirul de documente pentru obiectul cod este disponibil pe __doc__atributul obiectului cod respectiv și prin intermediul helpfuncției.

Următorul fișier Python arată declarația de docstrings într-un fișier sursă Python: 

"""The module's docstring"""

class MyClass:
    """The class's docstring"""

    def my_method(self):
        """The method's docstring"""

def my_function():
    """The function's docstring"""

Presupunând că codul de mai sus a fost salvat ca mymodule.py , următoarea este o sesiune interactivă care arată cum pot fi accesate șirurile de documente: 

>>> import mymodule
>>> help(mymodule)
The module's docstring
>>> help(mymodule.MyClass)
The class's docstring
>>> help(mymodule.MyClass.my_method)
The method's docstring
>>> help(mymodule.my_function)
The function's docstring
>>>

Instrumente care utilizează șiruri de documente

Vezi si

Referințe

linkuri externe