добавил примеры по работе с деревьями

2018-09-25 19:04:11 +03:00 · 2018-09-25 19:04:11 +03:00 · 59d791e97f
commit 59d791e97f
parent 73f3735bb6
12 changed files with 446 additions and 22 deletions
--- a/docfiles/providers/managers/trees/globalAttributeTree/attributes/manager.js
+++ b/docfiles/providers/managers/trees/globalAttributeTree/attributes/manager.js
@ -1,3 +1,5 @@
+/** @typedef {Trees.GlobalAttributeTree.Node.Attributes} NodeAttributes */
+
 /**
 * Интерфейс позволяющей пользователю работать с атрибутами ноды
 *
--- a/docfiles/providers/managers/trees/globalTree/node.js
+++ b/docfiles/providers/managers/trees/globalTree/node.js
@ -1,7 +1,44 @@
 /**
- * Нода дерева
- * Представляет интефрейс для доступа к данным глобальной ноды в ядре
- * Позволяет узнать потомков ноды
+ * Интерфейс доступа к содержимому глобальной ноды
+ *
+ * Здесь создаются менеджер по работе с вложенными нодами и менеджер типов ноды
+ *
+ * <br>
+ * Связанные объекты:
+ *
+ * - {@link Trees.GlobalTree} - Здесь можно найти примеры, как работать с глобальным деревом
+ * - {@link Trees.GlobalTree.Node.Children} - Здесь можно найти примеры, как работать с вложенными нодами
+ * - {@link Trees.GlobalTree.Node.NodeTypes} - Здесь можно найти примеры, как работать с типами ноды
+ *
+ *
+ * @example
+ * // Пример: Как получить ноду дерева?
+ *
+ * // Пример взят для дерева тополгии
+ * var tree = null;
+ * var node = null;
+ *
+ * // Осуществляем запрос к менеджеру деревьев, на получение провайдера дерева
+ * ps.pl.tm.get(new v2.string("st")).then(function(ref){
+ *     // ref - это ссылка на объект
+ *     // метод value возвращает целевой объект. В данном случае дерево Trees.SchemeTree
+ *     tree = ref.value();
+ *
+ *     // Доступ к ноде осуществляется похожим образом, но теперь вместо строки нужно указать v2.integer
+ *     // Так как возвратится нативный проимс, мы можем вернуть его и обработать в следующем then
+ *     return tree.get(v2.integer.from_number(0))
+ * }, function(err){
+ *     // в случае неудачи придет ошибка.
+ *     // обычно в ошибке содержится три переменные err - код ошибки, message - краткое описание, sub - если к этому
+ *     // привела другая ошибка внутри системы.
+ * }).then(function(ref){
+ *     // Вот мы и получили ноду.
+ *     node = ref.value();
+ * }, function(err){
+ *     // Отобразим ошибку
+ *     console.warn(err);
+ * })
+ *
 *
 * @class Node
 * @memberof Trees.GlobalTree
--- a/docfiles/providers/managers/trees/globalTree/tree.js
+++ b/docfiles/providers/managers/trees/globalTree/tree.js
@ -1,20 +1,93 @@
 /**
- * Глобальное дерево, от которого отнаследованы все остальные.
- * Копирует идеологию ядра. 
- * Ноды этого дерева имеют доступ только к списку своих потомков.
+ * Абстрактное дерево, от него наследуются все существующие деревья
+ *
+ * Ноды это дерева имеют доступ к списку нод, вложенных в них
+ *
+ * <br>
+ * Связанные объекты:
+ *
+ * - {@link Trees} - Здесь можно найти примеры, как работать с менеджером деревьев
+ * - {@link Trees.GlobalTree.Node} - Здесь можно найти примеры, как работать с содержимым глобальной ноды
+ *
+ * @example
+ * // Пример 1: Как получить глобальное дерево?
+ *
+ * // Пример взят для дерева тополгии
+ * var tree = null;
+ * ps.pl.tm.get(new v2.string("st")).then(function(ref){
+ *     // ref - это ссылка на объект
+ *     // метод value возвращает целевой объект. В данном случае дерево  {@type Trees.GlobalTree}
+ *     tree = ref.value();
+ * }, function(err){
+ *     // в случае неудачи придет ошибка.
+ *     // обычно в ошибке содержится три переменные err - код ошибки, message - краткое описание, sub - если к этому
+ *     // привела другая ошибка внутри системы.
+ * })
+ *
+ * @example
+ * // Пример 2: Как получить ноду дерева?
+ *
+ * // Пример взят для дерева тополгии
+ * var tree = null;
+ * var node = null;
+ *
+ * // Осуществляем запрос к менеджеру деревьев, на получение провайдера дерева
+ * ps.pl.tm.get(new v2.string("st")).then(function(ref){
+ *     // ref - это ссылка на объект
+ *     // метод value возвращает целевой объект. В данном случае дерево Trees.SchemeTree
+ *     tree = ref.value();
+ *
+ *     // Доступ к ноде осуществляется похожим образом, но теперь вместо строки нужно указать v2.integer
+ *     // Так как возвратится нативный проимс, мы можем вернуть его и обработать в следующем then
+ *     return tree.get(v2.integer.from_number(0))
+ * }, function(err){
+ *     // в случае неудачи придет ошибка.
+ *     // обычно в ошибке содержится три переменные err - код ошибки, message - краткое описание, sub - если к этому
+ *     // привела другая ошибка внутри системы.
+ * }).then(function(ref){
+ *     // Вот мы и получили ноду.
+ *     node = ref.value();
+ * }, function(err){
+ *     // Отобразим ошибку
+ *     console.warn(err);
+ * })
 *
 * @group manager
 * @class GlobalTree
+ * @extends manager
 * @memberof Trees
 */
 function GlobalTree() {
    /**
-     * Возвращает ссылку на ноду. В качестве идентификатора надо указать идентификатор ноды.
-     *  Работает через промис.
+     * Интерфейс доступа к ноде
+     *
+     * Ответ должен быть обработан в промисе,
+     *
+     * при успехе вернется {@link tools.reference} -> {@link Trees.GlobalTree.Node}
+     *
+     * при отмене вернется ошибка {@link Errors.PromiseReject}
+     *
+     * @example
+     * // Пример:
+     *
+     * // Допустим мы хотим получить корневую ноду.
+     * // Так сложилось, что корневая нода, всегда нулевая
+     * var nodeId = v2.integer.from_number(0);
+     *
+     * // Допустим что мы где-то уже получили дерево.
+     * var promise = tree.get(nodeId);
+     *
+     * promise.then(function(ref){
+     *     // Вот мы и получили ноду.
+     *     node = ref.value();
+     * }, function(err){
+     *     // Отобразим ошибку
+     *     console.warn(err);
+     * })
     *
     * @public
     * @function get
-     * @param {v2.integer} nodeId Уникальный идентификатор ноды в дереве
+     * @param {v2.integer} nodeId Идентификатор ноды в дереве
     * @returns {tools.promise}
     * @memberof Trees.GlobalTree
     */
@ -23,13 +96,30 @@ function GlobalTree() {
    };

    /**
-     * Позволяет удалить динамический атрибут ноды. 
-     * Возвращает булевое значение об операции
+     * Осуществляет уаление ноды из дерева.
+     *
+     * @example
+     * // Пример:
+     *
+     * // Допустим, что мы знаем, что в дереве существует нода с таким идентификатором
+     * var nodeId = v2.integer.from_number(1);
+     * var tree = null;
+     * ps.pl.tm.get(new v2.string("st")).then(function(ref){
+     *     // ref - это ссылка на объект
+     *     // метод value возвращает целевой объект. В данном случае дерево  {@type Trees.GlobalTree}
+     *     tree = ref.value();
+     *
+     *     // Произведет удаление ноды 1 из дерева
+     *     // Ответ придет по подписке на существование нод в дереве.
+     *     tree.remove(nodeId);
+     * }, function(err){
+     *     console.log(err)
+     * })
+     *
     *
     * @public
     * @function remove
-     * @param {v2.string} nodeId Уникальный идентификатор ноды в дереве
-     * @returns {boolean}
+     * @param {v2.integer} nodeId Идентификатор ноды в дереве
     * @memberof Trees.GlobalTree
     */
    this.remove = function(nodeId) {
@ -39,6 +129,7 @@ function GlobalTree() {
    /**
     *  Возвращает адрес дерева в системе
     *
+     *
     * @public
     * @function sys_addr
     * @returns {v2.address}
--- a/docfiles/providers/managers/trees/manager.js
+++ b/docfiles/providers/managers/trees/manager.js
@ -1,8 +1,45 @@
 /**
 * Менеджер деревьев.
+ *
 * Представляет собой интерфейс для доступа ко всем деревьям
+ *
 * Позволяет по тегу дерева получить на него ссылку.
- * На текущий момент содержит в себе:
+ *
+ * Деревья представляют собой следующую иерархию наследования
+ *
+ * <br>
+ *
+ * {@link Trees.GlobalTree} - любое дерево (обладает возможностью открывать свою иерархию)
+ * > {@link Trees.SchemeTree} - дерево топологии "st"
+ *
+ * > {@link Trees.GlobalAttributeTree} - любое дерево, которое обладает атрибутами (используется как дефолтное)
+ * > > {@link Trees.DesktopTree} - дерево рабочего стола "dsk"
+ *
+ * > > {@link Trees.UserAttributeTree} - дерево пользовательских параметров "uat"
+ *
+ * > > {@link Trees.RemoteModulesTree} - дерево сборщиков данных "rmt"
+ *
+ *
+ * <br>
+ * Список доступных тегов деревьев:
+ * - "cmp" - Компоненты
+ * - "cst" - Вложенность компонентов
+ * - "dsk" - Рабочий стол
+ * - "ect" - Дерево событий
+ * - "flt" - Фильтры
+ * - "edg" - Линки
+ * - "cedg" - Вложенность линков
+ * - "prf" - Профили
+ * - "rmt" - Сборщики данных
+ * - "st" - Схема объектов
+ * - "uat" - Пользовательские данные
+ *
+ * <br>
+ * Связанные объекты:
+ *
+ * - {@link Trees.GlobalTree} - Здесь можно найти примеры, как работать с нодами дерева
+ * - {@link Trees.GlobalTree.Node} - Здесь можно найти примеры, как работать с содержимым глобальной ноды
+ * - {@link Trees.GlobalAttributeTree.Node} - Здесь можно найти примеры, как работать с содержимым аттрибутной ноды
 *
 * @example
 * // Работа с деревом
@ -10,7 +47,7 @@
 * // доступ к конкретному дереву осуществляется по тагу дерева например ("st", "rmt", "uat")
 * // где st - дерево топологии, rmt - дерево сборщиков данных, uat - дерево в котором хранится информация о
 * // данных пользователя
- * ps.pl.tm(new v2.string("rmt")).then(function(ref){
+ * ps.pl.tm.get(new v2.string("rmt")).then(function(ref){
 *     // ref - это ссылка на объект
 *     // метод value возвращает целевой объект. В данном случае дерево  {@type Trees.GlobalTree}
 *     var tree = ref.value();
@ -25,20 +62,36 @@
 */
 function Trees() {
    /**
-     *  Вернет ссылку на дерево. В качестве идентификатора следует указать тег дерева.
+     * Доступ к дереву
+     *
+     * В качестве идентификатора следует указать тег дерева.
+     *
+     * при успехе вернется {@link tools.reference} -> {@link Trees.GlobalTree}
+     *
+     * при отмене вернется ошибка {@link Errors.PromiseReject}
+     *
+     * @example
+     * // Пример использования:
+     * // Результатом будет нативный промис.
+     * var promise = ps.pl.tm.get(new v2.string("rmt"));
     *
     * @public
     * @function get
     * @param {v2.string} treeTag Тег дерева. Например: "rmt", "uat"
-     * @returns {tools.promise}
+     * @returns {tools.promise(Trees.GlobalTree)}
     * @memberof Trees
     */
+
    this.get = function (treeTag) {

    };
    /**
     * Возвращает булевое значение о существовании дерева
     *
+     * @example
+     * // Пример:
+     * var exist = ps.pl.tm.is_exist(new v2.string("rmt"));
+     *
     * @public
     * @function is_tree_exist
     * @param {v2.string} treeTag Тег дерева. Например: "rmt", "uat"
@ -48,4 +101,4 @@ function Trees() {
    this.is_tree_exist = function (treeTag) {

    }
-}
+}
--- a/docfiles/providers/managers/trees/schemeTree/tree.js
+++ b/docfiles/providers/managers/trees/schemeTree/tree.js
@ -1,4 +1,42 @@
 /**
+ * Дерево представляющее топологию.
+ *
+ * Тег дерева "st"
+ *
+ * В Trees оно добавлено в фабрику, и создается из нее.
+ *
+ * ВАЖНО! У этого дерева нет атрибутов. Поэтому получить атрибут невозможно.
+ *
+ * Однако у нод этого дерева, есть возможно получить статические денные Адрес модели и является ли она Контейнером
+ *
+ * @example
+ * // Работа с деревом
+ * // Доступ к менеджеру деревьев находится в переменной ps.pl.tm (провайдеры -> мастер платформа -> менеджер деревьев)
+ * // доступ к конкретному дереву осуществляется по тагу дерева например ("st", "rmt", "uat")
+ * // где st - дерево топологии, rmt - дерево сборщиков данных, uat - дерево в котором хранится информация о
+ * // данных пользователя
+ *
+ * var tree = null;
+ * var node = null;
+ *
+ * ps.pl.tm.get(new v2.string("st")).then(function(ref){
+ *     // ref - это ссылка на объект
+ *     // метод value возвращает целевой объект. В данном случае дерево  {@type Trees.GlobalTree}
+ *     tree = ref.value();
+ *     return tree.get(v2.integer.from_number(0))
+ * }, function(err){
+ *     // в случае неудачи придет ошибка.
+ *     // обычно в ошибке содержится три переменные err - код ошибки, message - краткое описание, sub - если к этому
+ *     // привела другая ошибка внутри системы.
+ * }).then(function(ref){
+ *     // Вот мы и получили ноду.
+ *     node = ref.value();
+ * }, function(err){
+ *     // Отобразим ошибку
+ *     console.warn(err);
+ * })
+ *
+ *
 * @group manager
 * @class SchemeTree
 * @extends Trees.GlobalTree