Espruino:Примеры/Создание и подача на рассмотрение модулей (или изменений в них)

Материал из Онлайн справочника
Перейти к навигацииПерейти к поиску

Перевод: Максим Кузьмин (Cubewriter) Контакты:</br>* Skype: cubewriter</br>* E-mail: cubewriter@gmail.com</br>* Максим Кузьмин на freelance.ru
Проверка/Оформление/Редактирование: Мякишев Е.А.


Создание и подача на рассмотрение модулей (или изменений в них)[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. Готово! Теперь мы можем увидеть внесённые вами изменения и добавить их ко всем остальным.

См.также

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