Строка документации - Docstring

В программирование, а строка документации это строковый литерал указано в исходный код который используется, как комментарий, чтобы задокументировать определенный сегмент кода. В отличие от обычных комментариев исходного кода или даже специально отформатированных комментариев, таких как Javadoc документации, строки документации не удаляются из дерева исходных текстов при его анализе и сохраняются на протяжении всего времени выполнения программы. Это позволяет программисту проверять эти комментарии во время выполнения, например, как интерактивную справочную систему или как метаданные.

Кажется, впервые он был представлен в оригинале TECO реализация Emacs.[1]

Языки, поддерживающие строки документации, включают Python, Лисп, Эликсир, Clojure,[2] Корнишон,[3] Юля[4] и Haskell.[5]

Примеры реализации

Эликсир

Документация поддерживается на уровне языка в виде строк документации. Markdown - это фактический язык разметки Elixir, который выбирается для использования в строках документации:

def модуль MyModule делать  @moduledoc """  Документация к моему модулю. С ** форматированием **.  """  @doc "Привет"  def Мир делать    "Мир"  конецконец

Лисп

В Лиспе строки документации известны как строки документации. В Common Lisp Стандарт утверждает, что конкретная реализация может отказаться от строк документации, когда захотят, по любой причине. Когда они сохраняются, строки документации можно просматривать и изменять с помощью функции ДОКУМЕНТАЦИЯ.[6] Например:

 (defun фу () "всем привет" ноль) (документация #'фу функция) => "всем привет"

Python

Обычная практика документирования объекта кода во главе его определения фиксируется добавлением синтаксиса строки документации в языке Python.

Строка документации для объекта кода Python (модуля, класса или функции) является первым оператором этого объекта кода, непосредственно следующим за определением (оператором def или class). Оператор должен быть простым строковым литералом, а не каким-либо другим выражением. Строка документации для объекта кода доступна для этого объекта кода __doc__ атрибут и через помощь функция.

В следующем файле Python показано объявление строк документации в исходном файле Python:

"" "Строка документации модуля" ""учебный класс Мой класс:    "" "Строка документации класса" ""    def my_method(себя):        "" "Строка документации метода" ""def моя_функция():    "" "Строка документации функции" ""

Предполагая, что приведенный выше код был сохранен как mymodule.py, ниже представлен интерактивный сеанс, показывающий, как можно получить доступ к строкам документации:

>>> импорт мой модуль>>> помощь(мой модуль)Строка документации модуля>>> помощь(мой модуль.Мой класс)Строка документации класса>>> помощь(мой модуль.Мой класс.my_method)Строка документации метода>>> помощь(мой модуль.моя_функция)Строка документации функции>>>

Инструменты, использующие строки документации

Смотрите также

Рекомендации

  1. ^ «EMACS: расширяемый настраиваемый редактор дисплея».
  2. ^ Определение функции со строкой документации в Clojure
  3. ^ "Шаговые аргументы - строки документа". Архивировано из оригинал на 2016-01-31. Получено 2016-06-22.
  4. ^ http://docs.julialang.org/en/stable/manual/documentation/
  5. ^ https://hackage.haskell.org/package/docstrings
  6. ^ CLHS: ДОКУМЕНТАЦИЯ по стандартной универсальной функции ...

внешняя ссылка