Espruino:Примеры/Создание и подача на рассмотрение модулей (или изменений в них)
Создание и подача на рассмотрение модулей (или изменений в них)[1]
Если вы разработали код для взаимодействия с каким-то устройством (например, с LCD-дисплеем или каким-то аппаратным модулем), было бы здорово, если бы вы также создали и подали на рассмотрение JavaScript-модуль (библиотеку), которой могли бы воспользоваться другие люди при помощи команды вроде require("libname").
- Создайте аккаунт в GitHub.
- Зайдите сюда и кликните на кнопку Fork справа вверху. В результате на вашем GitHub-аккаунте появится полная копия всей документации этого репозитория.
- Кликните на папку «devices», затем на Add file > Create new file справа вверху.
- Назовите свой модуль в честь устройства, для которого разработан ваш код (но постарайтесь, чтобы название было как можно короче – как «PCD8544» для чипа, управляющего работой LCD-дисплея Nokia), а в конце добавьте «.js». В результате у вас должно получиться что-то вроде «MOD123.js».
* Скопируйте в этот файл вот этот шаблон:
/* Copyright (c) 2014 Ваше имя.
Информацию о лицензии скопируйте из файла LICENSE. */
/*
Краткое описание вашего модуля...
*/
var C = {
MY : 0x001, // описание
PRIVATE : 0x001, // описание
CONSTANTS : 0x00423 // описание
};
function MOD123(pin1,pin2) {
this.pin1 = pin1;
this.pin2 = pin2;
}
/** Здесь будут «публичные» константы */
MOD123.prototype.C = {
MY : 0x013, // описание
PUBLIC : 0x0541, // описание
CONSTANTS : 0x023 // описание
};
/** Большинство комментариев должны стоять вне функций... */
MOD123.prototype.foo = function() {
// вы можете использовать C.PRIVATE
// или this.C.PUBLIC
};
/** Большинство комментариев должны стоять вне функций... */
MOD123.prototype.bar = function() {
};
/** Это «экспортированная» функция,
так что вы можете использовать её при помощи
`require('MOD123.js').connect(pin1,pin2)` */
exports.connect = function (pin1, pin2) {
return new MOD123(pin1, pin2);
};
Чтобы протестировать свой модуль, скопируйте его полностью в правую часть Web IDE, но в самом верху у него должна быть строчка var exports={};. А внизу (там, где используете модуль) напишите var exports={} вместо require('MOD123').myfunction().
В качестве примера можете взглянуть на уже готовые модули (некоторые из них шаблону выше не следуют). Вот пара важных вещей, которые помогут сделать ваш модуль эффективнее:
- После загрузки модуля Espruino выполняет файл в его собственной области видимости, а затем сохраняет переменные и функции, которые были заданы в этой области видимости, в кэш модулей.
- Все функции и переменные, которые были заданы в корневой области видимости, будут общими и не будут дублироваться, если модуль будет использован в коде дважды. Но если вы зададите функцию внутри другой функции (например, внутри функции exports.myfunction) то эта функция будет создаваться снова при каждом вызове функции exports.myfunction.
- Большинство пользователей используют require() и в этом случае Web IDE загрузит минимизированную версию модуля. Это значит, что...
- ...все непубличные константы и функции будут минифицированы, если в этом будет смысл. Это сэкономит место и сделает библиотеку быстрее.
- ...все комментарии будут удалены.
- Даже если пользователь не использует минимизированную версию (возможно, он скопировал на карту Micro-SD полную версию или поменял настройки Web IDE):
- Espruino сохранит содержимое функций полностью (включая комментарии), но комментарии, находящиеся за пределами объявления функции, места занимать не будут.
- Кликните на кнопку Commit new file внизу. Если вы захотите что-то поменять, вы всегда сможете снова кликнуть на этот файл, а затем кликнуть на иконку с карандашом справа вверху, чтобы начать редактирование этого файла.
- Теперь нам нужно создать маленький файл для документации, чтобы ваш модуль смогли найти другие пользователи. Добавьте ещё один файл и назовите его «MOD123.md».
- Скопируйте в него шаблон ниже (первым словом в строчке KEYWORDS всегда должно стоять слово Module).
<!--- Copyright (c) 2014 Ваше имя.
Информацию о лицензии смотрите в файле LICENSE. -->
Формальное название вашего модуля.
=====================
* KEYWORDS: Module,список,слов,для,поиска,модуля,разделенных,запятой
Немного информации о модуле. Здесь можно, например,
немного описать устройство, для которого разработан этот модуль.
Устройство можно подключить следующим образом:
| Контакт | Espruino |
| Устройства | |
| ---------- | -------- |
| 1 (GND) | GND |
| 2 (VCC) | 3.3 |
| 3 (SIGIN) | A0 |
| 4 (SIGNOUT)| A1 |
Как использовать мой модуль:
```
var foo = require("MOD123").connect(A0,A1);
foo.usingFoo();
```
Описание модуля нужно будет отформатировать при помощи языка разметки Markdown. Примеры его использования ищите здесь или у других модулей на GitHub. Кроме того, если у вашего модуля больше одной функции, вы можете добавить в него APPEND_JSDOC. Это просканирует указанный JS-файл (то есть в данном случае – MOD123.js) на предмет экспортированных функций и комментариев в формате /** ... */, чтобы потом добавить их в ваш модуль в качестве справочной информации.
Reference
---------
* APPEND_JSDOC: MOD123.js
Кроме того, вы можете добавить в него APPEND_USES. Теперь если у какого-то руководства вверху будет написано USES: MOD123, то он будет указан на странице вашего модуля:
Using
-----
- APPEND_USES: MOD123
- Вот и всё! Теперь кликните на кнопку Commit New File внизу.
- При необходимости внесите нужные правки и изменения, а затем кликните на кнопку Pull Request справа вверху.
- Проверьте, правильные ли файлы там показаны (это должны быть файлы, которые мы создали в этом руководстве), а затем кликните на Create pull request.
- Откроется новая страница, где надо будет ввести название и описание пулл-реквеста. Указав их, нажмите на Create pull request. Готово! Теперь мы можем увидеть внесённые вами изменения и добавить их ко всем остальным.
См.также
Внешние ссылки
