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

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

Языки, поддерживающие строки документации, включают Python , Lisp , Elixir , Clojure , ^[1] Корнишон , ^[2] Юлия ^[3] и Хаскель . ^[4]

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

Эликсир

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

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

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

Лисп

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

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

Питон

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

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

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

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

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

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

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

кобра -док (Кобра)
доктест (Python)
Эпидок (Python)
Пидок (Питон)
Сфинкс (Питон)

См. также

Грамотное программирование – альтернативная парадигма комментирования кода
Простая старая документация – документация Perl

Ссылки

^ «Определение функции с помощью строки документации в Clojure» . Архивировано из оригинала 29 января 2013 г. Проверено 20 сентября 2017 г.
^ «Пошаговые аргументы — строки документа» . Архивировано из оригинала 31 января 2016 г. Проверено 22 июня 2016 г.
^ «Документация — документация Julia Language 0.4.1» . docs.julialang.org . Архивировано из оригинала 17 ноября 2015 г.
^ «Документационные строки» .
^ CLHS: ДОКУМЕНТАЦИЯ по стандартным универсальным функциям...

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

Строки документации Python Epydoc SourceForge на странице
Документация в GNU Emacs Lisp
Раздел из документации doxygen о строках документации Python

[1] «Определение функции с помощью строки документации в Clojure» . Архивировано из оригинала 29 января 2013 г. Проверено 20 сентября 2017 г.

[2] «Пошаговые аргументы — строки документа» . Архивировано из оригинала 31 января 2016 г. Проверено 22 июня 2016 г.

[3] «Документация — документация Julia Language 0.4.1» . docs.julialang.org . Архивировано из оригинала 17 ноября 2015 г.

[4] «Документационные строки» .

[5] CLHS: ДОКУМЕНТАЦИЯ по стандартным универсальным функциям...

[1]

[2]

[3]

[4]

[5]