add guide for providers

docfiles/mainpage/main.js

@@ -77,6 +77,58 @@
  *
  * По-сути он моделирует платформу со стороны сервера и содержит в себе менеджеры, через которые можно связываться с ядром.
  *
+ *
+ * <br>
+ * #### Как устроены провайдеры? (**Важно прочитать!**)
+ *
+ * Механизм провайдеров загружает данные из ядра и моделирует объект, если он изменяется во времени,
+ * и ядро допускает подписку на данные объекта.
+ *
+ * _К таким объектам относятся например:_
+ * {@link GroupTypes.GroupType GroupType},
+ * {@link Models.Model Model},
+ * {@link ModelTypes.ModelType ModelType},
+ * {@link Trees.GlobalTree.Node Node}.
+ *
+ * Основная идея состоит в том, что один раз загрузив данные, клиент не будет нагружать сервер запросами.
+ *
+ * Так что система провайдеров по факту кеширует в себе модели сервера, и если происходят обновления данных, то
+ *
+ * обновление происходит по частям.
+ *
+ * Вся основная работа с провайдерами начинается с точки доступа **ps.pl**. Это корневая платформа, она же мастер.
+ *
+ * Посмотреть какие есть интерфейсы у платформы можно {@link Platform тут}.
+ *
+ * Платформа содержит в себе все менеджеры, через которые можно осуществлять общение с сервером.
+ *
+ * _Например:_ {@link GroupTypes Типы компонентов}, {@link Models Менеджер моделей}, {@link Trees Менеджер деревьев}.
+ * <br>
+ * **Как корректно запрашивать и работать с данными предоставляемыми API?**
+ *
+ * - 1) У каждого менеджера как правило есть метод **get**. Этот метод, у кажого менеджера принимает свой тип данных.
+ * - - **get** всегда возвращает {@link tools.promise Промис}.
+ * - - Результатом промиса всегда будет {@link tools.reference ссылка}.
+ * - - **Работа ссылкой (ВАЖНО)**:
+ * - - - после того, как вы закончите работать с ссылкой, **ОБЯЗАТЕЛЬНО** вызвать у неё {@link tools.reference.reset reset}
+ * - - - если вы получили ссылку, и получили данные из объекта, вызовите у неё {@link tools.reference.reset reset}
+ * - - - если необходимо следить за состоянием, то сохраните ссылку в переменную и после того, как закончите работу с объектом вызовите {@link tools.reference.reset reset}
+ * - - - всегда вызывайте {@link tools.reference.reset reset}, если вам не нужен объект. В противном случае он не будет выгружаться из памяти.
+ *
+ * - 2) У кажого промиса есть возможность отмены. Если вам больше нет надобности ждать ответ, просто вызовите cancel.
+ * - 3) Будте внимательны к методам:
+ * - - все публичные методы и свойства будут идти без нижнего подчеркивания.
+ * - - все приватные методы будут и должны быть подписаны <_name>
+ * - - если нет нужного метода, а данные вы нашли где-то в приватных переменных, то следует разобраться почему, так. И:
+ * - - - а) сделать публичный методы.
+ * - - - б) спросить почему так сделано у автора.
+ * - 4) Перед началом работы стоит ознакомится с содержимым папки js/providers/system
+ * - - **base/base.js** - файл в котором определена машина состояний
+ * - - **base/item.js** - класс от которого наследуются все НЕ менеджеры
+ * - - **base/manager.js** - базовый класс для любого менеджера. Содержит API работы с менеджерами.
+ * - - **platform.js** - {@link Platform платформа}. Оно же точка доступа ps.pl.
+ *
+ *
  * <br>
  * Доступные менеджеры у платформы:
  * - {@link GroupTypes} - Менеджер, который позволяет получить данные по типу компонента, определен как **ps.pl.gtm**