Espruino:Примеры/Создание и подача на рассмотрение модулей (или изменений в них): различия между версиями
Myagkij (обсуждение | вклад) (Новая страница: «{{Espruino/Панель перехода}} {{Перевод от Сubewriter}} {{Myagkij-редактор}} =<ref>[ www.espruino.com - ]</ref>= <syntaxhighlig...») |
Нет описания правки |
||
(не показаны 3 промежуточные версии 2 участников) | |||
Строка 3: | Строка 3: | ||
{{Myagkij-редактор}} | {{Myagkij-редактор}} | ||
=<ref>[ www.espruino.com - ]</ref>= | =Создание и подача на рассмотрение модулей (или изменений в них)<ref>[https://www.espruino.com/Writing+Modules www.espruino.com - Writing and Submitting Modules (or changes)]</ref>= | ||
Если вы разработали код для взаимодействия с каким-то устройством (например, с [[LCD-дисплеем]] или каким-то аппаратным модулем), было бы здорово, если бы вы также создали и подали на рассмотрение JavaScript-модуль (библиотеку), которой могли бы воспользоваться другие люди при помощи команды вроде '''require("libname")'''. | |||
* Создайте аккаунт в [https://github.com/ GitHub]. | |||
* Зайдите [https://github.com/espruino/EspruinoDocs сюда] и кликните на кнопку Fork справа вверху. В результате на вашем GitHub-аккаунте появится полная копия всей документации этого репозитория. | |||
* Кликните на папку ''«devices»'', затем на '''Add file > Create new file''' справа вверху. | |||
* Назовите свой модуль в честь устройства, для которого разработан ваш код (но постарайтесь, чтобы название было как можно короче – как ''«[[PCD8544]]»'' для чипа, управляющего работой [[LCD-дисплея]] [[Nokia]]), а в конце добавьте ''«[[.js]]»''. В результате у вас должно получиться что-то вроде ''«MOD123.js»''. | |||
<syntaxhighlight lang="javascript | <syntaxhighlight lang="javascript"> | ||
* Скопируйте в этот файл вот этот шаблон: | |||
/* 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); | |||
}; | |||
</syntaxhighlight> | |||
Чтобы протестировать свой модуль, скопируйте его полностью в правую часть [[Web IDE]], но в самом верху у него должна быть строчка '''var exports={};'''. А внизу (там, где используете модуль) напишите '''var exports={}''' вместо '''require('MOD123').myfunction()'''. | |||
В качестве примера можете взглянуть на [http://www.espruino.com/modules/ уже готовые модули] (некоторые из них шаблону выше не следуют). Вот пара важных вещей, которые помогут сделать ваш модуль эффективнее: | |||
* После загрузки модуля [[Espruino]] выполняет файл в его собственной области видимости, а затем сохраняет переменные и функции, которые были заданы в этой области видимости, в кэш модулей. | |||
* Все функции и переменные, которые были заданы в корневой области видимости, будут общими и не будут дублироваться, если модуль будет использован в коде дважды. Но если вы зададите функцию внутри другой функции (например, внутри функции '''exports.myfunction''') то эта функция будет создаваться снова при каждом вызове функции '''exports.myfunction'''. | |||
* Большинство пользователей используют [[require()]] и в этом случае [[Web IDE]] загрузит минимизированную версию модуля. Это значит, что... | |||
** ...все непубличные константы и функции будут минифицированы, если в этом будет смысл. Это сэкономит место и сделает библиотеку быстрее. | |||
** ...все комментарии будут удалены. | |||
* Даже если пользователь не использует минимизированную версию (возможно, он скопировал на карту [[Micro-SD]] полную версию или поменял настройки [[Web IDE]]): | |||
** [[Espruino]] сохранит содержимое функций полностью (включая комментарии), но комментарии, находящиеся за пределами объявления функции, места занимать не будут. | |||
* Кликните на кнопку '''Commit new file''' внизу. Если вы захотите что-то поменять, вы всегда сможете снова кликнуть на этот файл, а затем кликнуть на иконку с карандашом справа вверху, чтобы начать редактирование этого файла. | |||
* Теперь нам нужно создать маленький файл для документации, чтобы ваш модуль смогли найти другие пользователи. Добавьте ещё один файл и назовите его ''«MOD123.md»''. | |||
* Скопируйте в него шаблон ниже (первым словом в строчке '''KEYWORDS''' всегда должно стоять слово '''Module'''). | |||
<syntaxhighlight lang="javascript"> | |||
<!--- 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(); | |||
``` | |||
</syntaxhighlight> | |||
Описание модуля нужно будет отформатировать при помощи языка разметки '''Markdown'''. Примеры его использования ищите [https://docs.github.com/en/github/writing-on-github здесь] или у других модулей на GitHub. | |||
Кроме того, если у вашего модуля больше одной функции, вы можете добавить в него '''APPEND_JSDOC'''. Это просканирует указанный JS-файл (то есть в данном случае – '''MOD123.js''') на предмет экспортированных функций и комментариев в формате '''/** ... */''', чтобы потом добавить их в ваш модуль в качестве справочной информации. | |||
<syntaxhighlight lang="javascript"> | |||
Reference | |||
--------- | |||
* APPEND_JSDOC: MOD123.js | |||
</syntaxhighlight> | |||
Кроме того, вы можете добавить в него '''APPEND_USES'''. Теперь если у какого-то [https://www.espruino.com/Writing+Tutorials руководства] вверху будет написано '''USES: MOD123''', то он будет указан на странице вашего модуля: | |||
<syntaxhighlight lang="javascript"> | |||
Using | |||
----- | |||
</syntaxhighlight> | </syntaxhighlight> | ||
* '''APPEND_USES: MOD123''' | |||
* Вот и всё! Теперь кликните на кнопку '''Commit New File''' внизу. | |||
* При необходимости внесите нужные правки и изменения, а затем кликните на кнопку '''Pull Request''' справа вверху. | |||
* Проверьте, правильные ли файлы там показаны (это должны быть файлы, которые мы создали в этом руководстве), а затем кликните на '''Create pull request'''. | |||
* Откроется новая страница, где надо будет ввести название и описание пулл-реквеста. Указав их, нажмите на '''Create pull request'''. Готово! Теперь мы можем увидеть внесённые вами изменения и добавить их ко всем остальным. | |||
=См.также= | =См.также= | ||
=Внешние ссылки= | =Внешние ссылки= | ||
Строка 19: | Строка 130: | ||
<references /> | <references /> | ||
{{Навигационная таблица/Espruino | {{Навигационная таблица/Портал/Espruino}} | ||
Текущая версия от 06:53, 24 мая 2023
Создание и подача на рассмотрение модулей (или изменений в них)[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. Готово! Теперь мы можем увидеть внесённые вами изменения и добавить их ко всем остальным.
См.также
Внешние ссылки