Docstring - Docstring

V programování , je dokumentačního řetězce je doslovný řetězec je uvedeno v zdrojovém kódu , který se používá, jako komentář , dokumentovat určitý segment kódu. Na rozdíl od konvenčních komentářů ke zdrojovým kódům nebo dokonce specificky formátovaných komentářů, jako je dokumentace Javadoc , nejsou řetězce dokumentů při analýze odstraněny ze zdrojového stromu a jsou zachovány po celou dobu běhu programu. To umožňuje programátorovi zkontrolovat tyto komentáře za běhu, například jako interaktivní systém nápovědy nebo jako metadata .

Zdá se, že byl poprvé představen v původní implementaci Emacsu TECO .

Mezi jazyky, které podporují řetězce dokumentů, patří Python , Lisp , Elixir , Clojure , Gherkin , Julia a Haskell .

Příklady implementace

Elixír

Dokumentace je podporována na jazykové úrovni ve formě docstrings. Markdown je de facto značkovací jazyk Elixir, který lze použít v dokumentových řetězcích: 

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

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

Lisp

V Lispu jsou řetězce dokumentů známy jako řetězce dokumentace. Standard Common Lisp uvádí, že konkrétní implementace se může rozhodnout zlikvidovat dokumenty, kdykoli chtějí, z jakéhokoli důvodu. Když jsou uchovávány, lze dokumenty zobrazit a měnit pomocí funkce DOKUMENTACE. Například: 

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

Krajta

Běžná praxe dokumentování objektu kódu na začátku jeho definice je zachycena přidáním syntaxe docstring v jazyce Python.

Dokumentový řetězec pro objekt kódu Pythonu (modul, třídu nebo funkci) je prvním příkazem tohoto objektu kódu, který bezprostředně následuje po definici (příkaz 'def' nebo 'class'). Příkaz musí být doslovný, nikoli žádný jiný druh výrazu. Dokumentový řetězec pro objekt kódu je k dispozici u __doc__atributu tohoto objektu kódu a prostřednictvím helpfunkce.

Následující soubor Pythonu ukazuje deklaraci docstrings ve zdrojovém souboru Pythonu: 

"""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"""

Za předpokladu, že výše uvedený kód byl uložen jako mymodule.py , následující je interaktivní relace ukazující, jak lze přistupovat k řetězcům docstrings: 

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

Nástroje využívající docstrings

Viz také

Reference

externí odkazy