В программировании , строка документация является строка символов , указанные в исходном коде , который используется, как комментарий к документу определенного сегмента кода. В отличие от обычных комментариев исходного кода или даже специально отформатированных комментариев, таких как документация Javadoc , строки документации не удаляются из дерева исходного кода при его анализе и сохраняются на протяжении всего времени выполнения программы. Это позволяет программисту проверять эти комментарии во время выполнения, например, как интерактивную справочную систему или как метаданные .
Похоже, что он был впервые представлен в исходной реализации Emacs TECO . [1]
Языки, поддерживающие строки документации, включают Python , Lisp , Elixir , Clojure , [2] Gherkin , [3] Julia [4] и Haskell . [5]
Примеры реализации
Эликсир
Документация поддерживается на уровне языка в виде строк документации. Markdown - это фактический язык разметки Elixir, который используется в строках документации:
def module MyModule do @moduledoc "" " Документация для моего модуля. С ** форматированием **. " "" @doc "Привет" def world do "World" end end
Лисп
В Лиспе строки документации известны как строки документации. Стандарт Common Lisp утверждает, что конкретная реализация может выбрать отбрасывание строк документации, когда они захотят, по любой причине. Когда они сохраняются, строки документации можно просматривать и изменять с помощью функции ДОКУМЕНТАЦИЯ. [6] Например:
( defun foo () "привет" nil ) ( документация # функция ' foo ' ) => "привет"
Python
Обычная практика документирования объекта кода во главе его определения фиксируется добавлением синтаксиса строки документации в языке Python.
Строка документации для объекта кода Python (модуля, класса или функции) является первым оператором этого объекта кода, следующим сразу за определением (оператором def или class). Оператор должен быть простым строковым литералом, а не каким-либо другим выражением. Строка документации для объекта кода доступна в __doc__
атрибуте этого объекта кода и через help
функцию.
В следующем файле Python показано объявление строк документации в исходном файле Python:
"" "Строка документации модуля" ""class MyClass : "" "Строка документации класса" "" 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 ) Строка документации функции >>>
Инструменты, использующие строки документации
- кобра -doc (Кобра)
- doctest (Python)
- Эпидок (Python)
- Pydoc (Python)
- Сфинкс (Python)
Смотрите также
- Грамотное программирование - альтернативная парадигма комментирования кода
- Обычная старая документация - Perl документация
Рекомендации
- ^ «EMACS: Расширяемый, настраиваемый редактор дисплея» .
- ^ Определение функции со строкой документации в Clojure
- ^ «Шаговые аргументы - Док-строки» . Архивировано из оригинала на 2016-01-31 . Проверено 22 июня 2016 .
- ^ http://docs.julialang.org/en/stable/manual/documentation/
- ^ https://hackage.haskell.org/package/docstrings
- ^ CLHS: ДОКУМЕНТАЦИЯ по стандартной универсальной функции ...
Внешние ссылки
- Строки документации Python на странице Epydoc Sourceforge
- Документация в GNU Emacs Lisp
- Раздел из Doxygen документации по Python строки документации