From 6b4b6ac92b1a88d66170b0c3f1225d31694ce853 Mon Sep 17 00:00:00 2001
From: Aleksey Chichenkov <a.chichenkov@initi.ru>
Date: Mon, 18 Mar 2019 17:03:37 +0300
Subject: [PATCH] add guide for providers

---
 docfiles/mainpage/main.js                | 52 ++++++++++++++++++++++++
 docfiles/providers/interface/platform.js | 39 ++++++++++++++++++
 2 files changed, 91 insertions(+)

diff --git a/docfiles/mainpage/main.js b/docfiles/mainpage/main.js
index 9cf6e33..d292a78 100644
--- a/docfiles/mainpage/main.js
+++ b/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**
diff --git a/docfiles/providers/interface/platform.js b/docfiles/providers/interface/platform.js
index d78817b..057db5e 100644
--- a/docfiles/providers/interface/platform.js
+++ b/docfiles/providers/interface/platform.js
@@ -1,4 +1,21 @@
 /**
+ * ### Платформа
+ * Основная точка доступа к данным.
+ *
+ * ```bash
+ * // доступ
+ * ps.pl
+ * ```
+ *
+ * Доступные менеджеры у платформы:
+ * - {@link GroupTypes} - Менеджер, который позволяет получить данные по типу компонента, определен как **gtm**
+ * - {@link ModelTypes} - Менеджер, который позволяет узнать о содержимом модели **mtm**
+ * - {@link Models} - Менеджер, для доступа к устройствам, определен как **mm**
+ * - {@link Trees} - Менеджер, для доступа к деревьям, определен как **tm**
+ * - {@link CoreConfig} - Менеджер, для доступа к конфигу платформы, определен как **core_config**
+ * - {@link CoreTranslations} - Менеджер, для доступа к переводам, определен как **core_translations**
+ * - {@link Datasource} - Менеджер, для к каталогу датасорсов, определен как **datasource_manager**
+ * - {@link UserManager} - Менеджер, для доступа к данным пользоваталей, определен как **user_manager**
  *
  * @group providers_interface
  * @namespace Platform
@@ -21,10 +38,29 @@ function Platform() {
      */
     this.mm = new Models();
 
+    /**
+     *
+     * @public
+     * @name mtm
+     * @type {ModelTypes}
+     * @memberof Platform
+     */
+    this.mtm = new ModelTypes();
+
+    /**
+     *
+     * @public
+     * @name gtm
+     * @type {GroupTypes}
+     * @memberof Platform
+     */
+    this.gtm = new GroupTypes();
+
     /**
      *
      * @public
      * @name core_translations
+     * @type {CoreTranslations}
      * @memberof Platform
      */
     this.core_translations = new CoreTranslations();
@@ -33,6 +69,7 @@ function Platform() {
      *
      * @public
      * @name core_config
+     * @type {CoreConfig}
      * @memberof Platform
      */
     this.core_config = new CoreConfig();
@@ -41,6 +78,7 @@ function Platform() {
      *
      * @public
      * @name datasource_manager
+     * @type {Datasource}
      * @memberof Platform
      */
     this.datasource_manager = new Datasource();
@@ -49,6 +87,7 @@ function Platform() {
      *
      * @public
      * @name user_manager
+     * @type {UserManager}
      * @memberof Platform
      */
     this.user_manager = new UserManager();