diff --git a/conf.json b/conf.json index 6006750..81262cf 100644 --- a/conf.json +++ b/conf.json @@ -10,7 +10,8 @@ }, "opts" : { "template": "templates/initi", - "encoding": "utf8", + "encoding": "utf8", + "readme": "", "recurse": true, "destination": "../documentation/" }, diff --git a/docfiles/libraries/v2/list.js b/docfiles/libraries/v2/list.js index 4b397da..b5d03e5 100644 --- a/docfiles/libraries/v2/list.js +++ b/docfiles/libraries/v2/list.js @@ -3,7 +3,7 @@ * @class list * @extends v2.base * @extends std.list - * @param _first_type {v2.vt.base} + * @param {v2.vt.base} _first_type * @memberof v2 */ function list(_first_type) { diff --git a/docfiles/mainpage/main.js b/docfiles/mainpage/main.js new file mode 100644 index 0000000..7d8ea5e --- /dev/null +++ b/docfiles/mainpage/main.js @@ -0,0 +1,13 @@ +/** + * AAAAA + * + * AAAAA + * + * AAAAA + * + * @name sdfasdf + * @mainpage + * @memberof mainpage + * @example + * dsfadfasdf + */ \ No newline at end of file diff --git a/docfiles/providers/managers/trees/globalAttributeTree/node.js b/docfiles/providers/managers/trees/globalAttributeTree/node.js index 57d7468..446bdd7 100644 --- a/docfiles/providers/managers/trees/globalAttributeTree/node.js +++ b/docfiles/providers/managers/trees/globalAttributeTree/node.js @@ -41,4 +41,19 @@ function Node() { this.am = function() { }; + + /** + * Возвращает ссылку на атрибут ноды. + * Работает через промис. + * + * @public + * @function get + * @param {v2.string} attributeName Имя атрибута + * @returns {tools.promise} + * @memberof Trees.GlobalAttributeTree.Node + */ + this.get = function(attributeName) { + + }; + } \ No newline at end of file diff --git a/docfiles/providers/managers/trees/globalTree/children/manager.js b/docfiles/providers/managers/trees/globalTree/children/manager.js index 707e109..ae8c0e6 100644 --- a/docfiles/providers/managers/trees/globalTree/children/manager.js +++ b/docfiles/providers/managers/trees/globalTree/children/manager.js @@ -1,7 +1,54 @@ /** @typedef {Trees.GlobalTree.Node.Children} NodeChildren */ /** - * Интерфейс позволяющей пользователю работать с потомками ноды + * ### Менеджер вложенных нод + * Предоставляет интерфейс доступа к списку и отслеживанию вложенных нод + * + *
+ * Связанные объекты: + * + * - {@link Trees.GlobalTree.Node} - Здесь можно найти примеры, как работать с глобальной нодой + * + * @example + * // Пример 1: Как получить Менеджер вложенных нод? + * + * // Пример взят для дерева тополгии + * var tree = null; + * var node = null; + * var cm = 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(); + * + * // Так как на этот момент node.cm еще не существует, нужно его подопнуть что бы он загрузился + * return node.children_manager() + * }, function(err){ + * // Отобразим ошибку + * console.warn(err); + * }).then(function(_cm){ + * // таким образом может быть получен МВН + * cm = _cm; + * + * // однако после этого действия можно его получать напрямую: + * cm = node.cm; + * }, function(err){ + * // Отобразим ошибку + * console.warn(err); + * }) * * @group manager * @class Children @@ -9,6 +56,10 @@ */ function Children() { /** + * ### Сигнал: добавление ноды. + * Оповещение о том, что добавилась новая нода в список вложенных нод + *
+ * Результат: {@link signals.node_children_add} * * @name s_node_add * @public @@ -18,35 +69,44 @@ function Children() { this.s_node_add = -1; /** + * ### Сигнал: удаление ноды. + * Оповещение о том, что удалилась нода из список вложенных нод + *
+ * Результат: {@link signals.node_children_remove} * - * @name s_change + * @name s_node_remove * @public * @memberof Trees.GlobalTree.Node.Children * @type {number} */ - this.s_change = -1; + this.s_node_remove = -1; /** * Возвращает список потомков ноды + * @example + * // Пример: + * // В данном случае я не рассматриваю полную цепочку получения МВН (т.к. это описано сверху). + * var children = node.cm.children(); + * + * // распечаетаем список идентификаторов: + * v2.tools.print(children); + * + * // Пример вывода: + * // + * // List(Integer) [ + * // 1, + * // 2, + * // 3, + * // 4, + * // 5 + * // ] * * @public - * @function get + * @function children * @returns {v2.list(v2.integer)} * @memberof Trees.GlobalTree.Node.Children */ this.children = function(attributeName) { }; - - /** - * Возвращает тип ноды, по ее идентификатору - * - * @public - * @function get_type_by_id - * @returns {v2.model_type} - * @memberof Trees.GlobalTree.Node.Children - */ - this.get_type_by_id = function(attributeName) { - - }; } \ No newline at end of file diff --git a/docfiles/providers/managers/trees/globalTree/node.js b/docfiles/providers/managers/trees/globalTree/node.js index 052db9b..e4dcff1 100644 --- a/docfiles/providers/managers/trees/globalTree/node.js +++ b/docfiles/providers/managers/trees/globalTree/node.js @@ -1,5 +1,6 @@ /** - * Интерфейс доступа к содержимому глобальной ноды + * ### Глобальная нода + * Предоставляет интерфейс доступа к содержимому глобальной ноды * * Здесь создаются менеджер по работе с вложенными нодами и менеджер типов ноды * @@ -45,27 +46,62 @@ */ function Node() { /** - * Возвращает ссылку на атрибут ноды. - * Работает через промис. + * ### Менеджер вложенных нод + * + * Внимание! На момент создания ноды, он не существует (что бы не съедать ресурсы системы). + * + * Поэтому вначале нужно запросить список чилдов, или загрузить его через this.children_manager * * @public - * @function get - * @param {v2.string} attributeName Имя атрибута - * @returns {tools.promise} + * @name cm * @memberof Trees.GlobalTree.Node + * @type {Trees.GlobalTree.Node.Children} */ - this.get = function(attributeName) { - - }; + this.cm = new Trees.GlobalTree.Node.Children(); /** - * Добавляет новый динамический атрибут в ноду. - * Ничего не возвращает. + * ### Добавление новой ноды + * + * Добавляет новую ноду используя текущую как парента. + * + * После добавления, менеджера вложенных нод, пошлет сигнал s_node_add + * + * + * @example + * // Пример: + * + * // При добавлении ноды, так же можно добавить произвольное количество атрибутов + * // каждый атрибут имеет метаданные + * // - removable : v2.boolean, + * // - editable : v2.boolean, + * // - visible : v2.boolean, + * // - type : v2.type + * // - value : v2.base + * + * // Создадим мапу для аттрибутов + * var my_attributes = new v2.map(v2.string.type, v2.vc.type); + * + * // Добавим в нее один атрибут + * my_attributes.put(new v2.string("my_attribute"), v2.vc.from_object({ + * removable: new v2.boolean(true), + * editable: new v2.boolean(true), + * visible: new v2.boolean(true), + * type: new v2.type(v2.string.type), + * value: new v2.string("Hello World!") + * })); + * + * // В данном примере, я не буду полностью доступаться до ноды по всей цепочке, (т.к. она описана выше) + * // Допустим что сейчас она есть на руках. + * + * // Добавим ноду + * node.add_node(my_attributes); + * + * // Все. Нода добавилась, теперь в чилды придет оповещение. * * @public * @function add_node - * @param {v2.vc} _attrs * @memberof Trees.GlobalTree.Node + * @param {v2.map(v2.string, v2.vc)} _attrs */ this.add_node = function(_attrs) { @@ -74,36 +110,117 @@ function Node() { /** * Возвращает уникальный идентификатор ноды. * + * @exapmle + * // Пример: + * var nodeId = node.id(); + * * @public * @function id - * @returns {v2.integer} * @memberof Trees.GlobalTree.Node + * @returns {v2.integer} */ this.id = function() { }; /** - * Возвращает список потомков ноды. - * Работает через промис. + * ### Возвращает список вложенных нод (Идентификаторы). + * + * А так же загрузит менеджер вложенных нод. После этого можно будет пользоваться this.cm + * + *
+ * Получив идентификаторы, можно сделать запрос на загрузку ноды у дерева. + * + *
+ * Результат: + * - в случае успеха возвращает {@link v2.list(v2.integer)} + * - в случае отмены возвращает {@link Errors.PromiseReject} + * + * @example + * // Пример: + * + * // Получаем промис на загрузку списка + * var promise = node.children(); + * + * // Навешиваем обработчики на промис + * promise.then(function(children){ + * // распечаетаем список идентификаторов: + * v2.tools.print(children); + * + * // Пример вывода: + * // + * // List(Integer) [ + * // 1, + * // 2, + * // 3, + * // 4, + * // 5 + * // ] + * }, function(err){ + * // выведем отмену + * console.warn(err); + * }) * * @public * @function children - * @returns {tools.promise} * @memberof Trees.GlobalTree.Node + * @returns {tools.promise(v2.list(v2.integer))} */ this.children = function() { }; /** - * Доступ к менеджеру детей + * ### Получить менеджер вложенных нод + * + * В данном случае если МВН не загружен, загрузит его. + * + * Если уже загружен то вернет. + * + *
+ * После вызова этого метода, будет проинициализированна переменная this.cm + * + *
+ * Результат: + * - в случае успеха вернется {@link Trees.GlobalTree.Node.Children} + * - в случае отмены вернется {@link Errors.PromiseReject} + * + * @example + * // Пример: + * // В данном примере, я не буду полностью доступаться до ноды по всей цепочке, (т.к. она описана выше) + * // Допустим что сейчас нода есть на руках. + * + * // Получаем промис на загрузку МВН + * var promise = node.children_manager(); + * + * // Обрабатываем результат + * promise.then(function(cm){ + * // Итак в переменной cm находится МВН + * + * // Пример использования такого подхода + * var children = cm.children(); + * }, function(err){ + * console.warn(err); + * }) + * * @public - * @function cm - * @returns {NodeChildren} + * @function children_manager * @memberof Trees.GlobalTree.Node + * @returns {tools.promise(NodeChildren)} */ - this.cm = function() { + this.children_manager = function() { + + }; + + /** + * Осуществляет проверку на существование менеджера нод. + * + * @public + * @function children_manager_exist + * @memberof Trees.GlobalTree.Node + * @returns {boolean} + */ + this.children_manager_exist = function() { }; } \ No newline at end of file diff --git a/docfiles/providers/managers/trees/manager.js b/docfiles/providers/managers/trees/manager.js index fc65518..2b268ab 100644 --- a/docfiles/providers/managers/trees/manager.js +++ b/docfiles/providers/managers/trees/manager.js @@ -1,5 +1,5 @@ /** - * Менеджер деревьев. + * ### Менеджер деревьев. * * Представляет собой интерфейс для доступа ко всем деревьям * diff --git a/docfiles/providers/signals/node_children.js b/docfiles/providers/signals/node_children.js new file mode 100644 index 0000000..3e89444 --- /dev/null +++ b/docfiles/providers/signals/node_children.js @@ -0,0 +1,69 @@ +/** + * ### Описание объекта сигнала + * Важно понимать, что такой объект существует только в документации, + * + * @example + * //Пример: + * // В данном примере я не буду рассматривать полную цепочку получения МВН (т.к. это описано выше). + * // Как пользоваться этим сигналом? + * + * // Вот так происходит добавление обработчика на этот сигнал. + * // dispatcher объявлен в глобальной области видимости + * // slot_node_remove - это идентификатор, по которому нужно будет отписаться от обработчика + * var slot_node_remove = dispatcher.add_slot(node.cm.s_node_remove, function(event){ + * // в переменной event всегда будет лежать объект и содержать поле node_id + * // таким образом мы получили идентификатор ноды, которая была удалена. + * var node_id = event.node_id; + * }); + * + * // Отписка производится подобным образом + * dispatcher.remove_slot(node.cm.s_node_remove, slot_node_remove); + * + * @class node_children_remove + * @memberof signals + */ +signals.node_children_remove = { + /** + * + * @public + * @name node_id + * @type {v2.integer} + * @memberof signals.node_children_remove + */ + node_id: new v2.integer(0,0) +}; + +/** + * ### Описание объекта сигнала + * Важно понимать, что такой объект существует только в документации, + * + * @example + * //Пример: + * // В данном примере я не буду рассматривать полную цепочку получения МВН (т.к. это описано выше). + * // Как пользоваться этим сигналом? + * + * // Вот так происходит добавление обработчика на этот сигнал. + * // dispatcher объявлен в глобальной области видимости + * // slot_node_add - это идентификатор, по которому нужно будет отписаться от обработчика + * var slot_node_add = dispatcher.add_slot(node.cm.s_node_add, function(event){ + * // в переменной event всегда будет лежать объект и содержать поле node_id + * // таким образом мы получили идентификатор ноды, которая была добавлена. + * var node_id = event.node_id; + * }); + * + * // Отписка производится подобным образом + * dispatcher.remove_slot(node.cm.s_node_add, slot_node_add); + * + * @class node_children_add + * @memberof signals + */ +signals.node_children_add = { + /** + * + * @public + * @name node_id + * @type {v2.integer} + * @memberof signals.node_children_add + */ + node_id: new v2.integer(0,0) +}; \ No newline at end of file diff --git a/docfiles/providers/signals/signals.js b/docfiles/providers/signals/signals.js new file mode 100644 index 0000000..be580c4 --- /dev/null +++ b/docfiles/providers/signals/signals.js @@ -0,0 +1,7 @@ +/** + * + * @namespace signals + */ +var signals = function () { + +}; \ No newline at end of file diff --git a/gen.sh b/gen.sh index 3b1c250..7273b50 100755 --- a/gen.sh +++ b/gen.sh @@ -1,4 +1,4 @@ #!/usr/bin/env bash rm -rf ../documentation -jsdoc -c conf.json \ No newline at end of file +jsdoc -c conf.json diff --git a/readme.txt b/readme.txt index b15abc4..5a16d53 100644 --- a/readme.txt +++ b/readme.txt @@ -1,4 +1,4 @@ -Установить nodejs +Установить nodejs Установить npm Установить JSDoc diff --git a/templates/initi/publish.js b/templates/initi/publish.js index 3df0f46..d2903aa 100644 --- a/templates/initi/publish.js +++ b/templates/initi/publish.js @@ -658,6 +658,15 @@ var find_first_members = function (_parent, _clss) { }; global.typedefs = {}; +global.mainpage_content = []; + +var find_tag_by_id = function (_tags, _tag_id) { + for (var a = 0; a < _tags.length; a++) { + var info = _tags[a]; + if (info.title == _tag_id) return true; + } + return false; +}; /** @param {TAFFY} taffyData See . @@ -722,6 +731,13 @@ exports.publish = function(taffyData, opts, tutorials) { if(doclet.kind == "typedef") { typedefs[doclet.longname] = doclet; } + + if(doclet.tags && find_tag_by_id(doclet.tags, "mainpage")){ + console.log(doclet); + + mainpage_content.push(doclet); + } + }); @@ -869,6 +885,7 @@ exports.publish = function(taffyData, opts, tutorials) { outputSourceFiles = conf.default && conf.default.outputSourceFiles !== false; // add template helpers + view.content = mainpage_content; view.find = find; view.linkto = linkto; view.replace_enters_to_br = replace_enters_to_br; @@ -892,7 +909,7 @@ exports.publish = function(taffyData, opts, tutorials) { files = find({kind: 'file'}); packages = find({kind: 'package'}); - generate('Home', + generate('Documentation: GUI 2.9.1-develop', packages.concat( [{ kind: 'mainpage', diff --git a/templates/initi/tmpl/layout.tmpl b/templates/initi/tmpl/layout.tmpl index b1d3ef8..400833c 100644 --- a/templates/initi/tmpl/layout.tmpl +++ b/templates/initi/tmpl/layout.tmpl @@ -2,7 +2,7 @@ - JSDoc: <?js= title ?> + Initi documentation for GUI(2.9.1-develop) <?js= title ?> diff --git a/templates/initi/tmpl/mainpage.tmpl b/templates/initi/tmpl/mainpage.tmpl index 64e9e59..cedfcb9 100644 --- a/templates/initi/tmpl/mainpage.tmpl +++ b/templates/initi/tmpl/mainpage.tmpl @@ -1,8 +1,13 @@ + +

diff --git a/templates/initi/tmpl/mainpage/each.tmpl b/templates/initi/tmpl/mainpage/each.tmpl new file mode 100644 index 0000000..3b975a8 --- /dev/null +++ b/templates/initi/tmpl/mainpage/each.tmpl @@ -0,0 +1,8 @@ + + + + + diff --git a/templates/initi/tmpl/mainpage/part.tmpl b/templates/initi/tmpl/mainpage/part.tmpl new file mode 100644 index 0000000..34568dd --- /dev/null +++ b/templates/initi/tmpl/mainpage/part.tmpl @@ -0,0 +1,17 @@ + + + +
+ + + +
+
Examples:
+ +
+