logger and transport API

api-references.md

@@ -6,17 +6,29 @@ For users guidance and CLI references see the main [documentation site](https://
 
 *Under developments. If you have questions contact the developers directly.*
 
-## Classes
+## Main classes
 
 - [Builder]{@link Builder}
 - [Container]{@link Container}
 - [Namespace]{@link Namespace}
-- [Logger]{@link Logger}
-- [Unit]{@link Unit}
-- [Expression]{@link Expression}
+
+## Modules
+
 - [ModuleSystem]{@link ModuleSystem}
 - [_Module]{@link _Module}
 
-- Component
-- _Size
-- Const
+## Elements
+
+- [Top]{@link Top}
+- [Component]{@link Component}
+- [Const]{@link Const}
+- [Unit]{@link Unit}
+- [Expression]{@link Expression}
+
+## Auxiliary
+
+- [Logger]{@link Logger}
+- [Transport]{@link Transport}
+- [JSONTransport]{@link JSONTransport}
+- [StdoutTransport]{@link StdoutTransport}
+- [StringTransport]{@link StringTransport}

src/logger.js

@@ -12,11 +12,25 @@ const levels = [
 ];
 
 class Logger {
-  constructor(showLogLevel = 'info'){
-    this.showLogLevel = showLogLevel;
+  /**
+   * 
+   * Object to work with several logging transports simultaneously.
+   * This class was inspired by <https://github.com/winstonjs/winston> package but much simpler.
+   * 
+   * @property {Transport[]} _transports storage for different log transports.
+   * @property {boolean} _hasErrors Value is equal to `true` if there is at least one log of level 'error' or higher.
+   */
+  constructor(){
     this._transports = [];
     this._hasErrors = false;
   }
+  /**
+   * To attach another transport to a logger.
+   * 
+   * @param {Transport} transport=() => {} `Transport` instance of function.
+   * 
+   * @returns {Logger} Self.
+   */
   addTransport(transport = () => {}){
     let checkTransport = (transport instanceof Transport)
       || typeof transport === 'function';
@@ -26,9 +40,20 @@ class Logger {
 
     return this;
   }
+  /**
+   * Remove all transports from a logger.
+   */
   clearTransport(){
     this._transports = [];
   }
+  /**
+   * To add a new log event to logger.
+   * This event will be then sent to all transports.
+   * 
+   * @param {string} level Log level: 'debug', 'info', 'warn', 'error', 'panic'
+   * @param {string} msg Log message.
+   * @param {object} opt Options for transport.
+   */
   log(level, msg, opt){
     let levelNum = levels.indexOf(level);
     if (levelNum < 0) {
@@ -46,40 +71,99 @@ class Logger {
       }
     });
   }
+  /**
+   * To add a 'debug' level message to logger.
+   * This is just a shortened version of the general log interface:
+   * ```js
+   * logger.debug('Something happens.')
+   * ```
+   * 
+   * which is the same as 
+   * ```js
+   * logger.log('debug', 'Something happens.')
+   * ```
+   * @param {string} msg Log message.
+   * @param {object} opt Options for transport.
+   */
   debug(msg, opt){
     this.log('debug', msg, opt);
   }
+  /**
+   * To add a 'info' level message to logger.
+   * This is just a shortened version of the general log interface:
+
+   * @param {string} msg Log message.
+   * @param {object} opt Options for transport.
+   */
   info(msg, opt){
     this.log('info', msg, opt);
   }
+  /**
+   * To add a 'warn' level message to logger.
+   * This is just a shortened version of the general log interface:
+
+   * @param {string} msg Log message.
+   * @param {object} opt Options for transport.
+   */
   warn(msg, opt){
     this.log('warn', msg, opt);
   }
+  /**
+   * To add a 'error' level message to logger.
+   * This is just a shortened version of the general log interface:
+
+   * @param {string} msg Log message.
+   * @param {object} opt Options for transport.
+   */
   error(msg, opt){
     this.log('error', msg, opt);
   }
+  /**
+   * To check if there is a log event of level 'error' or higher.
+   */
   get hasErrors(){
     return this._hasErrors;
   }
-  resetErrors(){ // should be used only for testing properties
+  // should be used only for testing properties
+  resetErrors(){
     this._hasErrors = false;
   }
 }
 
 class Transport {
+  /**
+   * Ways to analyze log events. Each transport does something with log event: prints to console, store in file, etc.
+   * See also {@link Logger}.
+   * 
+   * @param {string} showLevel If level is equal or higher than the value it will be analyzed.
+   *    Possible values: 'debug', 'info', 'warn', 'error', 'panic'
+   * 
+   * @property {number} showLevelNum Numeric identifier of showLevel value: 0, 1, 2, 3, 4.
+   */
   constructor(showLevel = 'info'){
     let showLevelNum = levels.indexOf(showLevel);
     if (showLevelNum < 0) {
       throw new TypeError(`Unknown logger level: "${showLevelNum}"`);
     }
     this.showLevelNum = showLevelNum;
   }
+  /**
+   * Actions to perform when call log in parent `Logger`.
+   */
   analyzer(){
     throw new Error('Transport is abstract class');
   }
 }
 
 class JSONTransport extends Transport{
+  /**
+   * Transport type storing everything in a JS array.
+   * 
+   * @extends Transport
+   * 
+   * @param {string} showLevel If level is equal or higher than the value it will be analyzed.
+   * @param {object[]} target Array to store logs.
+   */
   constructor(showLevel = 'info', target = []){
     super(showLevel);
     this.target = target;
@@ -92,6 +176,13 @@ class JSONTransport extends Transport{
   }
 }
 
+/**
+ * Transport type sending colored messages into console.
+ * 
+ * @extends Transport
+ * 
+ * @param {string} showLevel If level is equal or higher than the value it will be analyzed.
+ */
 class StdoutTransport extends Transport {
   analyzer(level, msg, opt, levelNum){
     let levelColors = [
@@ -109,6 +200,14 @@ class StdoutTransport extends Transport {
   }
 }
 
+/**
+ * Transport type sending strings into array.
+ * 
+ * @extends Transport
+ * 
+ * @param {string} showLevel If level is equal or higher than the value it will be analyzed.
+ * @param {object[]} target Array to store logs.
+ */
 class StringTransport extends Transport {
   constructor(showLevel = 'info', target = []){
     super(showLevel);

src/namespace.js

@@ -8,6 +8,10 @@ class Namespace extends Map {
    * 
    * @extends Map
    * 
+   * @property {Container} container Parent container.
+   * @property {string} _spaceName String identifier for namespace.
+   * @property {boolean} _isAbstract `true` if  namespace is abstract. `false` otherwise.
+   * 
    * @param {string} spaceName Space identifier.
    */
   constructor(spaceName){