joosy 1.2.0.beta.4 → 1.2.0.rc.1

data/source/joosy/modules/time_manager.coffee

@@ -56,6 +56,8 @@ Joosy.Modules.TimeManager =
   #
   # Drops all registered timeouts and intervals for this object
   #
+  # @private
+  #
   __clearTime: ->
     if @__intervals
       for entry in @__intervals

data/source/joosy/page.coffee

@@ -23,7 +23,7 @@ class Joosy.Page extends Joosy.Widget
   @layout: (layoutClass) ->
     @::__layoutClass = layoutClass
 
-  @include Joosy.Modules.Page.Scrolling
+  @concern Joosy.Modules.Page.Scrolling
   @extend  Joosy.Modules.Page.Title
 
   #
@@ -44,12 +44,9 @@ class Joosy.Page extends Joosy.Widget
     # we should declare ourselves as a relpacement to the layout, not the page
     @previous = @previous.layout if @layoutShouldChange && !@layout
 
-  ######
-  ###### Widget extensions
-  ######
-
   #
-  # This is required by {Joosy.Modules.Renderer}
+  # This is required by {Joosy.Modules.Renderer}.
+  #
   # Sets the base template dir to app_name/templates/pages
   #
   __renderSection: ->

data/source/joosy/resources/array.coffee

@@ -1,54 +1,139 @@
+#
+# The array structure with the support of dynamic rendering
+#
+# @include Joosy.Modules.Events
+# @extend  Joosy.Modules.Filters
+#
+# @example
+#   data = Joosy.Resources.Array.build 1, 2, 3
+#   data.get(0)                                     # 1
+#   data.set(0, 5)                                  # triggers 'changed'
+#   data.push(4)                                    # triggers 'changed'
+#   data.load(7, 8, 9)                              # triggers 'changed'
+#
 class Joosy.Resources.Array extends Array
-
   Joosy.Module.merge @, Joosy.Module
 
   @include Joosy.Modules.Events
-  @include Joosy.Modules.Filters
+  @extend Joosy.Modules.Filters
 
   @registerPlainFilters 'beforeLoad'
 
+  #
+  # Instantiates a new array
+  #
   @build: ->
     new @ arguments...
 
+  #
+  # Accepts numerous parameters (corresponding to array members)
+  #
   constructor: ->
     @__fillData arguments, false
 
+  #
+  # Replaces all the values with given
+  #
+  # @example
+  #   data = Joosy.Resources.Array.build 1, 2, 3
+  #   data.load 1, 2, 3
+  #
   load: ->
     @__fillData arguments
 
+  #
+  # Gets element by its index
+  #
+  # @example
+  #   data = Joosy.Resources.Array.build 1, 2, 3
+  #   data.get(0)                                   # 1
+  #
   get: (index) ->
     @[index]
 
+  #
+  # Sets element by its index
+  #
+  # @example
+  #   data = Joosy.Resources.Array.build 1, 2, 3
+  #   data.set(0, 2)                                   # 2
+  #   data                                             # [2, 2, 3]
+  #
   set: (index, value) ->
     @[index] = value
     @trigger 'changed'
     value
 
+  #
+  # Pushes element to the end of array
+  #
+  # @example
+  #   data = Joosy.Resources.Array.build 1, 2, 3
+  #   data.push(4)                                  # 4
+  #   data                                          # [1, 2, 3, 4]
+  #
   push: ->
     result = super
     @trigger 'changed'
     result
 
+  #
+  # Pops element of the end of array
+  #
+  # @example
+  #   data = Joosy.Resources.Array.build 1, 2, 3
+  #   data.pop()                                    # 3
+  #   data                                          # [1, 2]
+  #
   pop: ->
     result = super
     @trigger 'changed'
     result
 
+  #
+  # Shits element of the beginning of array
+  #
+  # @example
+  #   data = Joosy.Resources.Array.build 1, 2, 3
+  #   data.shift()                                  # 1
+  #   data                                          # [2, 3]
+  #
   shift: ->
     result = super
     @trigger 'changed'
     result
 
+  #
+  # Adds element of the beginning of array
+  #
+  # @example
+  #   data = Joosy.Resources.Array.build 1, 2, 3
+  #   data.unshift(0)                               # 4
+  #   data                                          # [0, 1, 2, 3]
+  #
   unshift: ->
     result = super
     @trigger 'changed'
     result
 
+  #
+  # Changes the content of an array, adding new elements while removing old elements.
+  #
+  # @example
+  #   data = Joosy.Resources.Array.build 1, 2, 3
+  #   data.splice(0, 2, 6)                          # 2
+  #   data                                          # [6, 3]
+  #
   splice: ->
     result = super
     @trigger 'changed'
     result
 
+  #
+  # Prepares data for internal storage
+  #
+  # @private
+  #
   __fillData: (data, notify=true) ->
     data = @slice.call(data, 0)
 

data/source/joosy/resources/hash.coffee

@@ -1,26 +1,64 @@
+#
+# The hash structure with the support of dynamic rendering
+#
+# @include Joosy.Modules.Events
+# @extend  Joosy.Modules.Filters
+#
+# @example
+#   data = Joosy.Resources.Hash.build field1: 'test', field2: 'test'
+#   data.get('field1')                              # 'test'
+#   data.set('field2', 'test2')                     # triggers 'changed'
+#
 class Joosy.Resources.Hash extends Joosy.Module
 
   @include Joosy.Modules.Events
-  @include Joosy.Modules.Filters
+  @extend Joosy.Modules.Filters
 
   @registerPlainFilters 'beforeLoad'
 
+  #
+  # Instantiates a new hash
+  #
   @build: ->
     new @ arguments...
 
+  #
+  # Internal helper for {Joosy.Modules.Resources.Function}
+  #
   __call: (path, value) ->
     if arguments.length > 1
       @set path, value
     else
       @get path
 
+  #
+  # Accepts hash of fields that have to be defined
+  #
   constructor: (data={}) ->
     @__fillData data, false
 
+  #
+  # Replaces all the values with given
+  #
+  # @example
+  #   data = Joosy.Resources.Hash.build foo: 'bar'
+  #   data.load bar: 'baz'
+  #   data                                          # { bar: 'baz' }
+  #
   load: (data) ->
     @__fillData data
     @
 
+  #
+  # Gets value by field name.
+  #
+  # @param [String] path              The path to the field that should be resolved
+  # @note Can resolve nested fields
+  #
+  # @example
+  #    data.get('field')              # { subfield: 'value' }
+  #    data.get('field.subfield')     # 'value'
+  #
   get: (path) ->
     [instance, property] = @__callTarget path, true
 
@@ -31,6 +69,17 @@ class Joosy.Resources.Hash extends Joosy.Module
     else
       instance[property]
 
+  #
+  # Sets value by field name.
+  #
+  # @param [String] path              The path to the field that should be resolved
+  # @param [Mixed] value              The value to set
+  # @note Can resolve nested fields
+  #
+  # @example
+  #    data.set('field', {subfield: 'value'})
+  #    data.set('field.subfield', 'value2')
+  #
   set: (path, value) ->
     [instance, property] = @__callTarget path
 
@@ -79,6 +128,9 @@ class Joosy.Resources.Hash extends Joosy.Module
     @trigger 'changed' if notify
     null
 
+  #
+  # @nodoc
+  #
   toString: ->
     "Hash: #{JSON.stringify(@data)}"
 

data/source/joosy/resources/rest.coffee

@@ -4,9 +4,11 @@
 #
 # Resource with REST/JSON backend
 #
+# @concern Joosy.Modules.Resources.Model
+#
 class Joosy.Resources.REST extends Joosy.Resources.Hash
 
-  @include Joosy.Modules.Resources.Model
+  @concern Joosy.Modules.Resources.Model
 
   @registerPlainFilters 'beforeSave'
 
@@ -17,7 +19,24 @@ class Joosy.Resources.REST extends Joosy.Resources.Hash
 
     data
 
-
+  #
+  # Registeres default options for all HTTP queries
+  #
+  # @param [Hash] options                  Options as a hash
+  # @param [Function<Hash>] options        Function that overrides options in given hash
+  #
+  # @example
+  #   class Test extends Joosy.Resources.REST
+  #     @requestOptions
+  #       headers:
+  #         'access-token': 'test'
+  #
+  # @example
+  #   class Test extends Joosy.Resources.REST
+  #     @requestOptions (options) ->
+  #       options.url = Config.baseUrl + options.url
+  #
+  #
   @requestOptions: (options) ->
     @::__requestOptions = options
 
@@ -60,6 +79,7 @@ class Joosy.Resources.REST extends Joosy.Resources.Hash
   #
   @at: ->
     @__atWrapper (callback) =>
+      # @nodoc
       class Clone extends @
         callback(@)
     , arguments...
@@ -289,16 +309,48 @@ class Joosy.Resources.REST extends Joosy.Resources.Hash
 
     result
 
+  #
+  # Updates the instance on the server with PUT query
+  #
+  # @param [Function<Mixed, REST>] callback
+  #
+  # @example
+  #   class Test extends Joosy.Resources.REST
+  #   test = Test.build id: 1, field1: 'test'
+  #
+  #   test.update (error, test) ->
+  #     unless error
+  #       # ...
+  #
   update: (callback) ->
     @send 'put', {params: @__applyBeforeSaves(@data)}, (error, data) =>
       @load data unless error
       callback? error, @
 
+  #
+  # Updates new entry on the server with local state with POST query
+  #
+  # @param [Function<Mixed, REST>] callback
+  #
+  # @example
+  #   class Test extends Joosy.Resources.REST
+  #   test = Test.build field1: 'test'
+  #
+  #   test.create (error, test) ->
+  #     unless error
+  #       # ...
+  #
   create: (callback) ->
     @constructor.send 'post', {params: @__applyBeforeSaves(@data)}, (error, data) =>
       @load data unless error
       callback? error, @
 
+  #
+  # Saves current state of instance (automatically choosing between updation and creation)
+  #
+  # @see Joosy.Resources.REST.create
+  # @see Joosy.Resources.REST.update
+  #
   save: (callback) ->
     if @id()
       @update callback
@@ -308,6 +360,8 @@ class Joosy.Resources.REST extends Joosy.Resources.Hash
   #
   # Wrapper for AJAX request
   #
+  # @private
+  #
   @__query: (path, method, params, callback) ->
     options =
       url: path
@@ -330,7 +384,9 @@ class Joosy.Resources.REST extends Joosy.Resources.Hash
     $.ajax options
 
   #
-  # utility function for better API support for unrequired first options parameter
+  # Utility function for better API support for unrequired first options parameter
+  #
+  # @private
   #
   __extractOptionsAndCallback: (options, callback) ->
     if typeof(options) == 'function'

data/source/joosy/resources/scalar.coffee

@@ -1,36 +1,82 @@
+#
+# The scalar value with the support of dynamic rendering
+#
+# @include Joosy.Modules.Events
+# @extend  Joosy.Modules.Filters
+#
+# @example
+#   data = Joosy.Resources.Scalar.build 1
+#   data.get()                             # 1
+#   data.set(2)                            # triggers 'changed'
+#
 class Joosy.Resources.Scalar extends Joosy.Module
 
   @include Joosy.Modules.Events
-  @include Joosy.Modules.Filters
+  @extend Joosy.Modules.Filters
 
   @registerPlainFilters 'beforeLoad'
 
+  #
+  # Instantiates a new instance
+  #
   @build: ->
     new @ arguments...
 
+  #
+  # Internal helper for {Joosy.Modules.Resources.Function}
+  #
   __call: ->
     if arguments.length > 0
       @set arguments[0]
     else
       @get()
 
+  #
+  # Accepts a value to encapsulate
+  #
   constructor: (value) ->
     @load value
 
+  #
+  # Replaces the value with given
+  #
+  # @example
+  #   data = Joosy.Resources.Scalar.build 1
+  #   data.load 2
+  #   data                                          # 2
+  #
   load: (value) ->
     @value = @__applyBeforeLoads(value)
     @trigger 'changed'
     @value
 
+  #
+  # Gets current value
+  #
   get: ->
     @value
 
+  #
+  # Replaces the value with given
+  #
+  # @see Joosy.Resources.Scalar.load
+  #
   set: (@value) ->
     @trigger 'changed'
 
+  #
+  # JS helper converting object to its internal value during basic operations
+  #
+  # @nodoc
+  #
   valueOf: ->
     @value.valueOf()
 
+  #
+  # String representation
+  #
+  # @nodoc
+  #
   toString: ->
     @value.toString()