Контрибьюторам
==============
Если вы решили помочь в разработке данной библиотеки или вам требуется внести некоторые изменения для своих нужд, эта документация будет вам полезна.

Code-style
----------
Есть несколько требований к стилю кода в данном проекте:

#### Одна сущность - один файл 
Каждый класс или отдельная функция должны быть оформлены в виде отдельного файла,
название которого состоит из имени этой сущности в css-case (нижний регистр, слова разделяются дефисами).

#### Документация кода
Все сущности должны иметь документацию в формате jsdoc. Подробнее об этом можно почитать [тут](http://usejsdoc.org/) 
или посмотреть примеры прямо в коде. Не обязательно подробно описывать работу функций или классов, 
достаточно краткого описания. Также обязательным является указание типа переменных
и возвращаемых значений.

В генераторе документации используется специальная директива `@exported` для указания под каким именем данный объект доступен в публичном неймспейсе (см. [src/audio.js](https://github.yandex-team.ru/music/audio/blob/mddoc/src/audio-player.js#L178))


Если требуется в коде визуально отделить один блок от другого, следует использовать вот такие вставки c описанием идущего
за ними блока
```
// =================================================================

//  Проверка доступности Flash-плеера

// =================================================================
```
Данный формат выбран т.к. многие IDE сворачивают многострочные комментарии, а это как раз в данном случае не нужно.
Подобный комментарий не будет свернут и он хорошо выделяется.

#### Форматирование
  - `camelCase` - все сущности в проекте именуются согласно форматированию camelCase. Имена классов начинаются с
    заглавной буквы, остальные сущности именуются с маленькой буквы.
  - `ALL_CAPS_SNAKE_CASE` - все имена констант записываются заглавными буквами, в качестве разделителя слов
    используется нижнее подчеркивание.
  - `_privateMethod` - приватные методы должны начинаться с подчеркивания. Все свойства считаются приватными и пишутся
    без подчеркивания.
  - `__boundMethod` - если требуется создавать версию метода, с привязанным контекстом, новый метод должен называться
    так же, как оригинальный и начинаться с 2х подчеркиваний (приватные методы в данном случае все равно начинаются с 2х
    подчеркиваний, а не с 3х). Такие методы следует создавать в конструкторе класса (желательно использовать именно такой
    подход при создании обработчиков событий).
  - `"Строки"` - строки заключаются в двойные кавычки.
  - `require('some-file')` - инструкции подключения файлов выносятся в начало файла. Имена файлов указываются в
    одинарных кавычках без расширения (расширение следует указывать явно только в том случае, если в имени файла есть точка).
    Если требуется подключать файлы json, их следует перевести в формат js, добавив в начало файла `module.exports =`.
  - `\n` - для переводов строк используется LF-нотация (Unix и OS X стандарт).
  - `;\n` - каждая инструкция должна завершаться точкой с запятой и переводом строки.
  - `\n&&`, ... - при необходимости переноса знак операции переносится в начало строки.
  - `    var a;` - для форматирования отступов используется 4 пробела.
  - `a = b + c` - знаки равенства, математических операций и сравнения следует отделять пробелами.
  - `var someFunction = function() {\n ... \n};` - функции объявляются через `var`. Не следует использовать именованные
    функции. Между объявлением функции/метода и скобками пробела быть не должно. Фигурные скобки ставятся на той же 
    строке и отделяются пробелом. После закрывающей фигурной скобки следует ставить точку с запятой. После открывающей 
    и перед закрывающей фигурной скобкой ставится перевод строки. Запись в одну строку допускается только в случае,
    если функция/метод содержит ровно 1 инструкцию.
  - `if (true) {\n ... \n} else {\n ... \n}` - в конструкции if-else не допускается опускание фигурных скобок. Фигурные
    скобки ставятся на той же строке и отделяются пробелом. После открывающей и перед закрывающей фигурной скобкой
    ставится перевод строки.    
  - `<-- 120 -->`  - длина строки кода или комментария не должна превышать 120 символов.

#### Циклы (на графе)
Граф зависимостей проекта не должен содержать циклов. Поясню: нельзя делать так, чтобы 
  - файл **A** использует файл **B**
  - файл **B** использует файл **A**

Данную конструкцию следует исправлять подобным образом:
  - файл **A** использует файлы **B** и **С**
  - файл **B** использует файл **C**

Сборка javascipt
----------------
Сборка библиотеки производится с помощью npm-пакетов [browserify](https://www.npmjs.com/package/browserify) и [uglify-js](https://www.npmjs.com/package/uglify-js).
Для того чтобы подготовить окружение для сборки библиотеки, требуется установить [node-js](https://nodejs.org/en/) и выполнить `npm install` в корне репозитория.
Сам процесс сборки доступен в двух вариантах: с помощью утилиты make (основой метод) и с помощью библиотеки [grunt](http://gruntjs.com/).

### Makefile
Является основным методом сборки. Доступные команды:

  - **make all** - делает полную сборку библиотеки
  - **make clean** - удаляет каталог сборки
  - **make build** - собирает библиотеку
  - **make minify** - собирает минифицированную версию библиотеки (не пересобирает библиотеку, если она была уже собрана через make build)
  
Если вызывать команду **make** без аргументов, то будет выполнен сценарий **make all**.
Перед тем как делать pull request, следует сделать полную сборку библиотеки с помощью make.

### Grunt
Запасной вариант сборки для тех, у кого по каким-то причинам нет возможности воспользоваться утилитой make.
Чтобы использовать сборку через grunt, требуется установить глобально пакет [grunt-cli](https://www.npmjs.com/package/grunt-cli) (`npm install -g grunt-cli`).
Доступные команды:

  - **grunt all** - делает полную сборку библиотеки
  - **grunt clean** - удаляет каталог сборки
  - **grunt build** - собирает библиотеку
  
Без аргументов **grunt** выполняет сценарий **grunt all**.


Сборка Flash
------------
Сборка Flash-плеера в автоматическом режиме не доступна. Для ручной сборки требуется настроить какой-либо сборщик (наиболее удобные: IntelliJ IDEA, FlashDevelop). Параметры, используемые для сборки: FlexSDK 3.6.0, целевая версия плеера - 9, основной класс - AudioManager, имя собранного файла - player-2_1.swf