Подписаться

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

Последняя правка сделана 2021-05-17 10:44:02 Править

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

. Похоже, что это было впервые введено в исходной реализации Emacs.

языков, которые вспомогательные строки документации включают Python, Lisp, Elixir, Clojure, Gherkin, Julia и Haskell.

Содержание

  • 1 Примеры реализации
    • 1.1 Elixir
    • 1.2 Lisp
    • 1.3 Python
  • 2 Инструменты, использующие строки документации
  • 3 См. также
  • 4 Ссылки
  • 5 Внешние ссылки

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

Эликсир

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

def module MyModule do @moduledoc "" "Документация для моего модуля. С ** форматированием **." "" @Doc "Hello" def world do " World "end end

Lisp

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

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

Python

Обычная практика документирования объекта кода в заголовок его определения захватывается добавлением синтаксиса строки документации в языке 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) Строка документации функции>>>

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

См. Также

Ссылки

Внешние ссылки

Содержание доступно по лицензии CC BY-SA 3.0 (если не указано иное).
Обратная связь: mail@alphapedia.ru
Соглашение
О проекте