cloud_powers 0.2.7 → 0.2.7.1

data/lib/cloud_powers/context.rb

@@ -17,16 +17,19 @@ module Smash
 
       # Attempts to create a Context out of the argument(s) you've
       # passed.
-      # === @params args <Hash|JSON|Array|enumerable list>
-      #   - exp Hash:
-      #     `{ task: 'demo', queue: [:backlog, :sned], pipe: :status_stream }`
-      #     each key is a module or class that is in CloudPowers and each value
-      #     is either an array of configurations information or a single configuration.
-      #   - exp Array
-      #     `[:task, 'demo', :queue, :backlog, :sned, :pipe, :status_stream]`
-      #     each key is followed by 0..n valid configurations information
-      # === @returns
-      #   `Smash::Context`
+      #
+      # Parameters
+      # * args +Hash+|+JSON+|+Array+|+enumerable list+
+      # * * expample +Hash+:
+      # * * * each key is a module or class that is in CloudPowers and each value
+      #       is either an array of configurations information or a single configuration.
+      #         { task: 'demo', queue: [:backlog, :sned], pipe: :status_stream }
+      # * * expample Array
+      # * * * each key is followed by 0..n valid configurations information
+      #         [:task, 'demo', :queue, :backlog, :sned, :pipe, :status_stream]
+      #
+      # Returns
+      # +Smash::Context+
       def initialize(args)
         unless valid_args?(args)
           raise ArgumentError.new 'Can be either a Hash, JSON, or an Enumerable ' +
@@ -36,8 +39,12 @@ module Smash
         @structure = decipher(args)
       end
 
-      # # Decipher figures out which translation method to use by making some simple
-      # # type checks, etc. and then routing the args to the correct method.
+      # Decipher figures out which translation method to use by making some simple type checks, etc.
+      # and then routing the args to the correct method.
+      #
+      # Notes
+      # * See +#translate_json()+
+      # * See +#translate_list()+
       def decipher(args)
         case args
         when Hash
@@ -50,33 +57,61 @@ module Smash
       end
 
       # Creates a flat Array of the 2-D Array that gets returned from `#simplify()`
-      # === @returns <Array>
+      #
+      # Returns +Array+
+      #
+      # Example
+      #   example_context.structure
+      #   # => { task: 'demo', queue: [:backlog, :sned], pipe: [:status_stream] }
+      #   example.flatten
+      #   # => [:task, 'demo', :queue, :backlog, :sned, :pipe, :status_stream]
+      #
+      # Notes
+      # * See +#simplify()
+      # * See +#Array::flatten()+
       def flatten
         simplify.flatten
       end
 
       # Create an array version of @sructure by calling `#to_a()` on it
-      # === @returns Array<Array..n>
-      # TODO: Check if this has a limit to n-layers
+      #
+      # Returns
+      # <tt>Array[Array..n]</tt>
+      #
+      # Example
+      #   example_context.structure
+      #   # => { task: 'demo', queue: [:backlog, :sned], pipe: [:status_stream] }
+      #   example.simplify
+      #   # => [:task, 'demo', :queue, [:backlog, :sned], :pipe, [:status_stream]]
+      #
+      # Notes
+      # * This uses the different Constants, like Smash, Synapse and anything it can find
+      #   to decide what should be used as a key and what its following values array should
+      #   contain.  It basically says:
+      #   1. if the nth item is a known key (from the above search), add it as an object in the Array.
+      #   2. else, add it to the last sub-Array
+      #   3. move to n+1 in the +structure Hash+
+      # * TODO: Check if this has a limit to n-layers
       def simplify
         @structure.to_a
       end
 
       # A Hash that represents the resources and some configuration for them
-      # === @returns Hash
+      #
+      # Returns +Hash+
       def structure
         modify_keys_with(@structure) { |key| key.to_sym }
       end
 
       # Valid scheme for @structure is assured by running the arguments through
-      # the decipher method, which is how @structure is set in `#new(args)`
+      # the decipher method, which is how @structure is set in +#new(args)+
       def structure=(args)
         @structure = decipher(args)
       end
 
       # Parse the given JSON
-      # === @param: json_string <String::Json>
-      # === @returns <Hash>
+      # Parameters: json_string <String::Json>
+      # Returns <Hash>
       def translate_json(json_string)
         begin
           JSON.parse(json_string)
@@ -124,19 +159,19 @@ module Smash
       #        ...
       #      }
       #      ```
-      # === @returns Hash
+      # Returns Hash
       #   If `#valid_package_hash?()` is called on this Hash, it will return true
       def translate_list(list)
         list.first.kind_of?(Enumerable) ? translate_simplified(list) : translate_flattened(list)
       end
 
       # Translates an Array into a valid @structure Hash
-      # === @param arr <Array>
+      # Parameters arr <Array>
       #   e.g.
       #   ```Ruby
       #   [:task, 'demo', :queue, 'name1', {other config hash},...,:pipe, 'name1']
       #   ```
-      # === @returns Hash
+      # Returns Hash
       #   calling `#valid_hash_format?()` on returned Hash will return true
       def translate_flattened(list)
         arr = list.to_a
@@ -155,7 +190,7 @@ module Smash
       end
 
       # Translates a 2D Array into a valid @structure Hash
-      # === @param arr <Array>
+      # Parameters arr <Array>
       #   e.g.
       #   ```
       #     [
@@ -169,7 +204,7 @@ module Smash
       #   - First object of each inner-Array is the key
       #   - All following values in that inner Array are separate configuration
       #     information pieces that can be used in the `#create!()` method for that particular resource
-      # === @returns Hash
+      # Returns Hash
       #   well formatted for the @structure
       def translate_simplified(arr)
         arr.inject({}) do |hash, key_config_map|
@@ -181,7 +216,7 @@ module Smash
       end
 
       # Uses `#to_json()` on the @structure
-      # === @returns Hash
+      # Returns Hash
       def to_json
         structure.to_json
       end
@@ -190,8 +225,8 @@ module Smash
       # class _should_ exist in.  It can be a vanilla version, where the @structure
       # is a Hash, structured correctly or it can be serialized into JSON or it can
       # be an Array
-      # === @params: args String
-      # === @returns: Boolean
+      # Parameters args String
+      # Returns Boolean
       def valid_args?(args)
         case args
         when Hash
@@ -208,16 +243,16 @@ module Smash
       # Makes sure that the list is enumerable and that at least the first term
       # is a resource name from Smash::CloudPowers.  All other objects can
       # potentially be configurations.
-      # @param list <Array|Enumerable>
-      # @returns Boolean
+      # Parameters list <Array|Enumerable>
+      # Returns Boolean
       def valid_array_format?(list)
         use = list.first.kind_of?(Enumerable) ? list.first.first : list.first
         ((list.kind_of? Enumerable) && (available_resources.include?(to_pascal(use).to_sym)))
       end
 
       # Makes sure that each key is the name of something CloudPowers can interact with
-      # @param hash <Hash>
-      # @returns Boolean
+      # Parameters hash <Hash>
+      # Returns Boolean
       def valid_hash_format?(hash)
         keys_arr = hash.keys.map { |key| to_pascal(key).to_sym }
         (keys_arr - available_resources).empty?

data/lib/cloud_powers/helper.rb

@@ -10,16 +10,19 @@ module Smash
 
       # Sets an Array of instance variables, individually to a value that a
       # user given block returns.
-      # === @params Array
-      #   * each object will be used as the name for the instance variable that
+      #
+      # Parameters
+      #
+      # * keys +Array+
+      # * * each object will be used as the name for the instance variable that
       #     your block returns
-      # === @&block (optional)
-      #   * this is called for each object in the Array and is used as the value
+      # +block+ (optional)
+      #   * this block is called for each object in the Array and is used as the value
       #   for the instance variable that is being named and created for each key
-      # === @return Array
+      # Returns Array
       #   * each object will either be the result of `#instance_variable_set(key, value)`
       #     or instance_variable_get(key)
-      # === Sampel use:
+      # Example
       #   keys = ['foo', 'bar', 'yo']
       #
       #   attr_map!(keys) { |key| sleep 1; "#{key}:#{Time.now.to_i}" }
@@ -37,7 +40,7 @@ module Smash
 
       # This is a way to find out if you are trying to work with a resource
       # available to CloudPowers
-      # === @returns <Array>
+      # Returns <Array>
       #   * Use `.constants` to find all the modules and classes available.
       # Notes:
       #   TODO: make this smartly pick up all the objects, within reason and
@@ -64,17 +67,17 @@ module Smash
 
       # Allows you to modify all keys, including nested, with a block that you pass.
       # If no block is passed, a copy is returned.
-      # === @params
+      # Parameters
       #   * params Hash|Array
       # === @&block (optional)
       #   * should modify the key and return that value so it can be used in the copy
-      # === @returns
+      # Returns
       #   * a copy of the given Array or Hash, with all Hash keys modified
       # === Sample use:
       #   hash = { 'foo' => 'v1', 'bar' => { fleep: { 'florp' => 'yo' } } }
       #   modify_keys_with(hash) { |key| key.to_sym }
       #   # => { foo: 'v1', bar: { fleep: { florp: 'yo' } } }
-      # === Notes:
+      # Notes:
       #   * see `#modify_keys_with()` for handling first-level keys
       #   * see `#pass_the_buck()` for the way nested structures are handled
       #   * case for different types taken from _MultiXML_ (multi_xml.rb)
@@ -117,29 +120,29 @@ module Smash
       end
 
       # Gets the path from the environment and sets @log_file using the path
-      # @returns @log_file path <String>
+      # Returns @log_file path <String>
       def log_file
         @log_file ||= zfind('LOG_FILE')
       end
 
-      # === @returns: An instance of Logger, cached as @logger
+      # Returns An instance of Logger, cached as @logger
       def logger
         @logger ||= create_logger
       end
 
       # Allows you to modify all first-level keys with a block that you pass.
       # If no block is passed, a copy is returned.
-      # === @params
+      # Parameters
       #   * params Hash|Array
       # === @&block (optional)
       #   * should modify the key and return that value so it can be used in the copy
-      # === @returns
+      # Returns
       #   * a copy of the given Array or Hash, with all Hash keys modified
       # === Sample use:
       #   hash = { 'foo' => 'v1', 'bar' => { fleep: { 'florp' => 'yo' } } }
       #   modify_keys_with(hash) { |k| k.to_sym }
       #   # => { :foo => 'v1', :bar => { fleep: { 'florp' => 'yo' } } }
-      # === Notes:
+      # Notes:
       #   * see `#deep_modify_keys_with()` for handling nested keys
       #   * case for different types taken from _MultiXML_ (multi_xml.rb)
       def modify_keys_with(params)
@@ -155,7 +158,7 @@ module Smash
       # until another bit of logic does what it's supposed to, kind of like
       # continuing to poll something and doing something when a package is ready
       # to be taken and processed.
-      # === @params:
+      # Parameters
       #   * [allowed_attempts] or Infinity(default) <Number>: The number of times
       #       the loop should be allowed to...well, loop, before a failed retry occurs.
       #   * &test <Block>: A predicate method or block of code that is callable
@@ -175,9 +178,9 @@ module Smash
       end
 
       # Gives the path from the project root to lib/tasks[/#{file}.rb]
-      # === @params:
+      # Parameters
       #   * [file] <String>: name of a file
-      # === @returns:
+      # Returns
       #   * path[/file] <String>
       #   * If a `file` is given, it will have a '.rb' file extension
       #   * If no `file` is given, it will return the `#task_require_path`
@@ -187,7 +190,7 @@ module Smash
       end
 
       # Gives the path from the project root to lib/tasks[/file]
-      # === @params String (optional)
+      # Parameters String (optional)
       #   * file_name name of a file
       # ===  @returns:
       #   * path[/file] String
@@ -198,8 +201,8 @@ module Smash
       end
 
       # Change strings into camelCase
-      # === @params var String
-      # === @returns String
+      # Parameters var String
+      # Returns String
       #     * givenString
       def to_camel(var)
         var = var.to_s unless var.kind_of? String
@@ -209,8 +212,8 @@ module Smash
       end
 
       # Change strings hyphen-delimited-string
-      # === @params var String
-      # === @returns String
+      # Parameters var String
+      # Returns String
       #     * given-string
       def to_hyph(var)
         var = var.to_s unless var.kind_of? String
@@ -225,8 +228,8 @@ module Smash
       end
 
       # Change strings into snake_case and add '@' at the front
-      # === @params var String
-      # === @returns String
+      # Parameters var String
+      # Returns String
       #     * @given_string
       def to_i_var(var)
         var = var.to_s unless var.kind_of? String
@@ -234,8 +237,8 @@ module Smash
       end
 
       # Change strings into PascalCase
-      # === @params var String
-      # === @returns String
+      # Parameters var String
+      # Returns String
       #     * givenString
       def to_pascal(var)
         var = var.to_s unless var.kind_of? String
@@ -243,8 +246,8 @@ module Smash
       end
 
       # Change strings into a ruby_file_name with extension
-      # === @params var String
-      # === @returns String
+      # Parameters var String
+      # Returns String
       #     * given_string.rb
       #     * includes ruby file extension
       #     * see #to_snake()
@@ -253,8 +256,8 @@ module Smash
       end
 
       # Change strings into snake_case
-      # === @params var String
-      # === @returns String
+      # Parameters var String
+      # Returns String
       #     * given_string
       #     * will not have file extensions
       #     * see #to_ruby_file_name()
@@ -271,9 +274,9 @@ module Smash
 
       # This method provides a default overrideable message body for things like
       # basic status updates.
-      # === @params Hash
+      # Parameters Hash
       #   - instanceId:
-      # === Notes:
+      # Notes:
       #   - camel casing is used on the keys because most other languages prefer
       #   that and it's not a huge problem in ruby.  Besides, there's some other
       #   handy methods in this module to get you through those issues, like

data/lib/cloud_powers/node.rb

@@ -11,7 +11,7 @@ module Smash
       include Smash::CloudPowers::SelfAwareness
       include Smash::CloudPowers::Zenv
       # These are sensible defaults that can be overriden by providing a Hash as a param.
-      # @params [opts <Hash>]
+      # Parameters [opts <Hash>]
       #   the opts Hash should have values that should be used instead of the given
       #   configuration.
       def node_config(opts = {})
@@ -36,7 +36,7 @@ module Smash
       # configuration for the #run_instances method by using the opts hash that was
       # provided as a parameter.
       #
-      # === @params opts Hash (optional)
+      # Parameters opts Hash (optional)
       #   an optional instance configuration hash can be passed, which will override
       #   the values in the default configuration returned by #instance_config()
       def spin_up_neurons(opts = {})

data/lib/cloud_powers/self_awareness.rb

@@ -17,7 +17,7 @@ module Smash
 
       # Gets the instance time or the time it was called and as seconds from
       # epoch
-      # === @returns Integer
+      # Returns Integer
       # TODO: use time codes
       def boot_time
         begin
@@ -68,16 +68,18 @@ module Smash
       end
 
       # Assures there is always a valid instance id because many other Aws calls require it
-      # === @returns: String
+      # Returns String
       def instance_id
         @instance_id ||= metadata_request('instance_id')
       end
 
       # Gets and sets the public hostname of the instance
-      # === @returns String
-      # === Notes:
-      #     * When this is being called from somewhere other than an Aws instance, a hardcoded example URL is returned
-      #       because of the way instance metadata is retrieved
+      # Returns
+      #   +String+
+      # Notes
+      # When this is being called from somewhere other than an Aws instance,
+      # a hardcoded example URL is returned
+      # because of the way instance metadata is retrieved
       def instance_url
         @instance_url ||= unless zfind('TESTING')
           hostname_uri = 'http://169.254.169.254/latest/meta-data/public-hostname'
@@ -90,8 +92,13 @@ module Smash
       # Makes the http request to self/meta-data to get all the metadata keys or,
       # if a key is given, the method makes the http request to get that
       # particular key from the metadata
-      # === @param: key String (optional)
-      # === @returns:
+      #
+      # Parameters
+      # * <tt>key</tt> - +String+ (optional)
+      #
+      # === Returns
+      # * +Array+ if key is blank
+      # * +String+ if key is given
       def metadata_request(key = '')
         key = to_hyph(key)
         begin
@@ -110,7 +117,7 @@ module Smash
       end
 
       # Return the time since boot_time
-      # === @returns: Integer
+      # Returns Integer
       # Notes:
       # * TODO: refactor to use valid time stamps for better tracking.
       # * reason -> separate regions or OSs etc.
@@ -131,9 +138,9 @@ module Smash
       end
 
       # Get the instance status.
-      # === @params: id String (optional)
+      # Parameters id String (optional)
       #     * if no id is given, self-instance ID is returned
-      # === @returns: String
+      # Returns String
       def status(id = @instance_id)
         begin
           ec2.describe_instances(dry_run: zfind('TESTING'), instance_ids: [id]).

data/lib/cloud_powers/synapse/broadcast/broadcast.rb

@@ -11,11 +11,17 @@ module Smash
           include Smash::CloudPowers::Zenv
 
           # Prefers the given arn but it can make a best guess if none is given
+          #
+          # Returns
+          # arn +String+ - arn for this resource
           def arn
             set_arn || "arn:aws:sns:#{zfind(:region)}:#{zfind(:accound_number)}:#{set_name}"
           end
 
           # Prefers the given name but it can parse the arn to find one
+          #
+          # Returns
+          # name +String+ - name for this resource
           def name
             set_name || set_arn.split(':').last
           end
@@ -23,26 +29,38 @@ module Smash
         #################
 
         # Creates a connection point for 1..N nodes to create a connection with the Broadcast
-        # def create_distributor(channel)
-        #   sns.create_application_platform()
-        # end
+        #
+        # Parameters
+        # * channel +String+
+        #
+        # Notes
+        # This method is not implemented yet (V 0.2.7)
+        def create_distributor(channel)
+          sns.create_application_platform()
+        end
 
         # Creates a point to connect to for information about a given topic
-        # === @params: name String: the name of the Channel/Topic to be created
-        # === @returns: Broadcast::Channel representing the created channel
+        #
+        # Parameters
+        # * name +String+ - the name of the Channel/Topic to be created
+        #
+        # Returns
+        # +Broadcast::Channel+ - representing the created channel
         def create_channel!(name)
           resp = sns.create_topic(name: name)
           Channel.new(nil, resp.topic_arn)
         end
 
         # Deletes a topic from SNS-land
-        # === @params: channel <Broadcast::Channel>
+        #
+        # Parameters
+        # * channel <Broadcast::Channel>
         def delete_channel!(channel)
           sns.delete_topic(topic_arn: channel.arn)
         end
 
         # Creates a connection to the Broadcast so that new messages will be picked up
-        # === @params: channel <Broadcast::Channel>
+        # Parameters channel <Broadcast::Channel>
         def listen_on(channel)
           sns.subscribe(
             topic_arn:    channel.arn,
@@ -52,7 +70,7 @@ module Smash
         end
 
         # Lists the created topics in SNS.
-        # === @returns results <Array
+        # Returns results <Array
         def real_channels
           results = []
           next_token = ''
@@ -66,7 +84,7 @@ module Smash
         end
 
         # Send a message to a Channel using SNS#publish
-        # === @params: [opts <Hash>]:
+        # Parameters [opts <Hash>]:
         #   this includes all the keys AWS uses but for now it only has defaults
         #   for topic_arn and the message
         def send_broadcast(opts = {})