О документации


 

К списку содержимого:

 

 

Цель написания этой документации состоит в том, чтобы всесторонне объяснить Node.js API как с общепринятой, так и с концептуальной точки зрения. Каждый раздел описывает встроенный модуль или высокоуровневый концепт.

В некоторых случаях типы переменных, параметры методов и параметры, относящиеся к обработке событий, детально описаны по ссылкам под заголовком темы.

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

Каждый .html и .json файл генерируется на основе соответствующего .md файла в каталоге doc/api дерева Node.js. Документация создается при помощи tools/doc/generate.js скрипта. Шаблон HTML находится в папке doc/template.html.

 

Индекс стабильности

 

В этой документации вы можете увидеть показатели стабильности раздела. Node.js API до сих пор изменяется и обрастает новыми улучшениями, по этой причине некоторые части этой документации являются менее стабильными, чем другие. Основополагающие принципы АПИ вряд ли подвергнутся изменениям. Другие могут быть новыми или экспериментальными, или же вовсе небезопасными и находящимися в процессе редизайна.

 

Индексы стабильности представлены следующими:

 

Стабильность: 0 – устарело или набрало много негативных отзывов

Эта фича является проблемной и ее планируют изменить. Не стоит полагаться на нее. Использование фичи может вызвать ошибки. Не стоит ожидать от нее обратной совместимости.

Стабильность: 1 – Экспериментальная

Фича изменяется и не допускается флагом командной строки. Может быть изменена или удалена в последующих версиях.

Стабильность: 2 – Стабильная

АПИ является удовлетворительным. Совместимость с NPM имеет высший приоритет и не будет нарушена кроме случаев явной необходимости.

Стабильность: 3 – Закрыто

Принимаются только фиксы, связанные с безопасностью, производительностью или баг-фиксы. Пожалуйста, не предлагайте изменений АПИ в разделе с таким индикатором, они будут отклонены.

 

Вывод в формате JSON

 

Стабильность: 1 – Экспериментальная

Каждый HTML файл имеет соответствующий JSON файл с аналогичными данными. Эта фича была добавлена в Node.js v0.6.12. Является экспериментальной.

 

Системные вызовы и страницы

 

Системные вызовы типа open(2) и read(2) определяют интерфейс между пользовательскими программами и предустановленными операционными системами. Функции Node, которые позволяют просто развернуть системный вызов, как fs.open(), задокументируют его. Ссылка в документе отсылает на справочные страницы, которые описывают принцип работы системных вызовов.

 

Примечание: некоторые системные вызовы, по типу lchown(2), являются специфичными для BSD. Это значит, что fs.lchown будет работать только на Mac OS X и других BSD-системах и будут недоступными для Linux.

Большинство unix-вызовов имеют эквивалентные Windows-вызовы, однако, поведение их может отличаться от такового на Linux и OS X. Примеры случаев, когда невозможно заменить семантику системных вызовов Unix на Windows, находятся в Node issue 4760.