Войти
В программировании строка документации является указанным строковым литералом в исходном коде, который используется, как комментарий , для документирования определенного сегмента кода. В отличие от обычных комментариев исходного кода или даже специально отформатированных комментариев, таких как документация Javadoc, строки документации не удаляются из дерева исходного кода при его синтаксическом анализе и сохраняются на протяжении всего времени выполнения программы. Это позволяет программисту проверять эти комментарии во время выполнения, например, как интерактивную справочную систему или как метаданные.
. Похоже, что это было впервые введено в исходной реализации Emacs.
языков, которые вспомогательные строки документации включают Python, Lisp, Elixir, Clojure, Gherkin, Julia и Haskell.
Документация поддерживается на уровне языка в виде строк документации. Markdown - это фактический язык разметки Elixir, который используется в строках документации:
def module MyModule do @moduledoc "" "Документация для моего модуля. С ** форматированием **." "" @Doc "Hello" def world do " World "end end
В Лиспе строки документации известны как строки документации. Стандарт Common Lisp утверждает, что конкретная реализация может выбрать отбрасывать строки документации, когда они захотят, по любой причине. Когда они сохраняются, строки документации можно просматривать и изменять с помощью функции ДОКУМЕНТАЦИЯ. Например:
(defun foo () "hi there" nil) (documentation # 'foo' function) =>"hi there"
Обычная практика документирования объекта кода в заголовок его определения захватывается добавлением синтаксиса строки документации в языке Python.
Строка документации для объекта кода Python (модуля, класса или функции) является первым оператором этого объекта кода, непосредственно следующим за определением (оператором def или class). Оператор должен быть простым строковым литералом, а не каким-либо другим выражением. Строка документации для объекта кода доступна в атрибуте __doc__этого объекта кода и через функцию help.
В следующем файле Python показано объявление строк документации в исходном файле Python:
"" "Строка документации модуля" "" class MyClass (object): "" "Строка документации класса" "" def my_method (self): "" "Строка документации метода" "" def my_function (): "" "Строка документации функции" ""
Предполагая, что приведенный выше код был сохранен как mymodule.py, следующий интерактивный сеанс показывает, как к строкам документации можно получить доступ:
>>>import mymodule>>>help (mymodule) Строка документации модуля>>>help (mymodule.MyClass) Строка документации класса>>>help (mymodule.MyClass.my_method) Строка документации метода>>>help (mymodule.my_function) Строка документации функции>>>
