From 486e71df935db035df589c06c43d192848aafac2 Mon Sep 17 00:00:00 2001
From: Artur Arseniev <artur.catch@hotmail.it>
Date: Wed, 20 Apr 2016 14:50:06 +0200
Subject: [PATCH] Update Panel with comments

---
 src/panels/main.js | 126 ++++++++++++++++++++++++++++++++-------------
 1 file changed, 89 insertions(+), 37 deletions(-)

diff --git a/src/panels/main.js b/src/panels/main.js
index 14ceb868f..da4a67f52 100644
--- a/src/panels/main.js
+++ b/src/panels/main.js
@@ -2,51 +2,93 @@ define(function(require) {
 	/**
 	 * @class 	Panel
 	 * @param 	{Object} Configurations
-	 * 
+	 *
 	 * @return	{Object}
  	 * */
-	function Panel(config)
-	{
-		var c				= config || {},
-			defaults		= require('./config/config'),
-			Panels			= require('./model/Panels'),
-			PanelsView		= require('./view/PanelsView');
+	function Panel(config){
+		var c = config || {},
+			defaults = require('./config/config'),
+			Panels = require('./model/Panels'),
+			PanelsView = require('./view/PanelsView');
 
-	    // Set default options
+	  // Set default options
 		for (var name in defaults) {
 			if (!(name in c))
 				c[name] = defaults[name];
 		}
-		
-		this.panels			= new Panels(c.defaults);
-		var obj				= {
-				collection	: this.panels,
-		    	config		: c,
+
+		var panels = new Panels(c.defaults);
+		var obj = {
+			collection : panels,
+			config : c,
 		};
-		
-	    this.PanelsView 	= new PanelsView(obj);
-	}
-	
-	Panel.prototype	= {
-			
-			getPanels	: function(){
-				return this.panels;
+
+	  var PanelsViewObj = new PanelsView(obj);
+
+	  return {
+
+	  	/**
+	  	 * Returns the collection of panels
+	  	 * @return {Collection} Collection of panel
+	  	 */
+	  	getPanels: function(){
+				return panels;
 			},
-			
-			addPanel	: function(obj){
-				return this.panels.add(obj);
+
+			/**
+			 * Add new panel to the collection
+			 * @param {Object|Panel} panel Object with right properties or an instance of Panel
+			 * @return {Panel} Added panel. Useful in case of passed argument was an Object
+			 * @example
+			 * var newPanel = panelService.addPanel({
+			 *  id: 'myNewPanel',
+			 * 	visible	: true,
+			 * 	buttons	: [...],
+			 * });
+			 */
+			addPanel: function(panel){
+				return panels.add(panel);
 			},
-			
+
+			/**
+			 * Get panel by ID
+			 * @param  {string} id Id string
+			 * @return {Panel|null}
+			 * @example
+			 * var myPanel = panelService.getPanel('myNewPanel');
+			 */
 			getPanel	: function(id){
-				var res	= this.panels.where({id: id});
+				var res	= panels.where({id: id});
 				return res.length ? res[0] : null;
 			},
-			
-			addButton	: function(panelId, obj){
+
+			/**
+			 * Add button to the panel
+			 * @param {string} panelId Panel's ID
+			 * @param {Object|Button} button Button object or instance of Button
+			 * @return {Button|null} Added button. Useful in case of passed button was an Object
+			 * @example
+			 * var newButton = panelService.addButton('myNewPanel',{
+			 * 	id: 'myNewButton',
+			 * 	className: 'someClass',
+			 * 	command: 'someCommand',
+			 * 	attributes: { title: 'Some title'},
+			 * 	active: false,
+			 * });
+			 */
+			addButton	: function(panelId, button){
 				var pn	= this.getPanel(panelId);
-				return pn ? pn.get('buttons').add(obj) : null;
+				return pn ? pn.get('buttons').add(button) : null;
 			},
-			
+
+			/**
+			 * Get button from the panel
+			 * @param {string} panelId Panel's ID
+			 * @param {string} id Button's ID
+			 * @return {Button|null}
+			 * @example
+			 * var button = panelService.getButton('myPanel','myButton');
+			 */
 			getButton	: function(panelId, id){
 				var pn	= this.getPanel(panelId);
 				if(pn){
@@ -55,7 +97,19 @@ define(function(require) {
 				}
 				return null;
 			},
-			
+
+			/**
+			 * Render panels and buttons
+			 * @return {HTMLElement}
+			 */
+			render		: function(){
+				return PanelsViewObj.render().el;
+			},
+
+			/**
+			 * Active activable buttons
+			 * @private
+			 */
 			active		: function(){
 				this.getPanels().each(function(p){
 	    			p.get('buttons').each(function(btn){
@@ -64,11 +118,9 @@ define(function(require) {
 	    			});
 	    		});
 			},
-			
-			render		: function(){
-				return this.PanelsView.render().el;
-			},
-	};
-	
+
+	  };
+	}
+
 	return Panel;
 });
\ No newline at end of file