numerousapp 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5d5d927781f67b4b8929965a109a0f1e3398ef79
-  data.tar.gz: 338338af020ac429ce9e8cfe3c2a76cd425f48ba
+  metadata.gz: 01cd1c5e889cbf214c82da8f8901ea435602708e
+  data.tar.gz: 8772cd439ca04a25860ddf8c47e4f836c7d46606
 SHA512:
-  metadata.gz: aedd071bc1f66a16f68c1a361e799cb6e6b89c1603dcce55ee9af101e0fe5a0d29b7332bc7424e2f6257dc962e87d68624fc30551e04dcbee21e5809cec81a4d
-  data.tar.gz: b260a3ec6fbe3b8731713f8467e28e1094b43c98700e4fc29e71eaff65b7ecafd7eee4e3440b161e7c84ee194dc10374747f037d09d3edceef710f021f11fd8a
+  metadata.gz: 15582f2a034419114a327c990326a08db2455f1c0f4a30eb8e3cb15bcfbd89e677d93598566eae20754316a8c4d7cf887703f23e05acf33f29f7bf77b4f25f6c
+  data.tar.gz: 5c47dd449c711afce6e558b69e5fe752a331ce55e0374e19b2f7ee3e2bf6745050a613d7bdb44feeb7884c898963be8db8aa99c4783b976d0237868469bca6e4

data/lib/numerousapp.rb

@@ -38,7 +38,22 @@ require 'json'
 require 'net/http'
 require 'uri'
 
+#
+# NumerousError exceptions indicate errors from the server
+#
 class NumerousError < StandardError
+    #
+    # @!attribute msg
+    #      human-targeted error message as a string
+    #
+    # @!attribute code
+    #      HTTP error code (e.g., 404)
+    #
+    # @!attribute details
+    #      hash containing more ad-hoc information, most usefully :id which
+    #      is the URL that was used in the request to the server
+    #
+
     def initialize(msg, code, details)
         super(msg)
         @code = code
@@ -48,20 +63,47 @@ class NumerousError < StandardError
     attr_accessor :code, :details
 end
 
+#
+# A NumerousAuthError occurs when the server rejects your credentials,
+# Usually means your apiKey is (or has become) bad.
+#
 class NumerousAuthError < NumerousError
 end
 
+#
+# A NumerousMetricConflictError occurs when you write to a metric
+# and specified "only if changed" and your value 
+# was (already) the current value
+# 
 class NumerousMetricConflictError < NumerousError
 end
 
 #
-# This class is not meant for public consumption but it subclassed
-# into Numerous and NumerousMetric. It encapsultes all the details
-# of talking to the numerous server, dealing with chunked APIs, etc.
+# == NumerousClientInternals 
+#
+# Handles details of talking to the numerousapp.com server, including
+# the (basic) authentication, handling chunked APIs, json vs multipart APIs,
+# fixing up a few server response quirks, and so forth. It is not meant 
+# for use outside of Numerous and NumerousMetric.
 #
 class NumerousClientInternals
 
+    #
+    # @param apiKey [String] API authentication key
+    # @param server [String] Optional (keyword arg). Server name.
+    #
+    # @!attribute agentString 
+    #    @return [String] User agent string sent to the server.
+    #
+    # @!attribute [r] serverName
+    #    @return [String] FQDN of the target NumerousApp server.
+    #
+    # @!attribute [r] debugLevel
+    #    @return [Fixnum] Current debugging level; use debug() method to change.
+    #
     def initialize(apiKey, server:'api.numerousapp.com')
+
+
         @serverName = server
         @auth = { user: apiKey, password: "" }
         u = URI.parse("https://"+server) 
@@ -74,7 +116,13 @@ class NumerousClientInternals
         @debugLevel = 0
     end
     attr_accessor :agentString
+    attr_reader :serverName, :debugLevel
 
+    # Set the debug level
+    #
+    # @param [Fixnum] lvl 
+    #   The desired debugging level. Greater than zero turns on debugging.
+    # @return [Fixnum] the previous debugging level.
     def debug(lvl=1)
         prev = @debugLevel
         @debugLevel = lvl
@@ -88,7 +136,7 @@ class NumerousClientInternals
 
     protected
 
-    VersionString = '20141223.1x'
+    VersionString = '20141224.1'
 
     MethMap = {
         GET: Net::HTTP::Get,
@@ -96,7 +144,7 @@ class NumerousClientInternals
         PUT: Net::HTTP::Put,
         DELETE: Net::HTTP::Delete
     }
-
+    private_constant :MethMap
 
     #
     # This gathers all the relevant information for a given API
@@ -298,6 +346,9 @@ class NumerousClientInternals
 
     # generic iterator for chunked APIs
     def chunkedIterator(info, subs={}, block)
+        # if you didn't specify a block... there's no point in doing anything
+        if not block; return nil; end
+
         api = makeAPIcontext(info, :GET, subs)
         list = []
         nextURL = api[:basePath]
@@ -323,12 +374,47 @@ class NumerousClientInternals
     end
 end
 
+#
+# == Numerous
+#
+# Primary class for accessing the numerousapp server.
+#
+# === Constructor
+#
+#   You must supply an API key:
+#      nr = Numerous.new('nmrs_3xblahblah')
+#
+#   You can optionally override the built-in server name
+#      nr = Numerous.new('nmrs_3xblahblah', server:'test.server.com')
+#
+# === Server return values
+#
+# For most operations the NumerousApp server returns a JSON representation
+# of the current or modified object state. This is converted to a ruby
+# Hash of <string-key, value> pairs and returned from the appropriate methods.
+#
+# For some operations the server returns only a success/failure code.
+# In those cases there is no useful return value from the method; the 
+# method succeeds or else raises an exception (containing the failure code).
+#
+# For the collection operations the server returns a JSON array of dictionary
+# representations, possibly "chunked" into multiple request/response operations.
+# The enumerator methods (e.g., "metrics") implement lazy-fetch and hide 
+# the details of the chunking from you. They simply yield each individual
+# item (string-key Hash) to your block.
+#
+# === Exception handling
+#
+# Almost every API that interacts with the server will potentially 
+# raise a {NumerousError} (or subclass thereof). This is not noted specifically
+# in the doc for each method unless it might be considered a "surprise"
+# (e.g., ping always returns true else raises an exception). Rescue as needed.
+#
 
 class Numerous  < NumerousClientInternals
 
     # path info for the server-level APIs: create a metric, get user info, etc
-
-    APIInfo = {
+    APIInfo = {        
       # POST to this to create a metric
       create: { 
           path: '/v1/metrics',
@@ -363,57 +449,116 @@ class Numerous  < NumerousClientInternals
           # no entry needed for GET because no special codes etc
       }
     }
+    private_constant :APIInfo
 
-
-    # return User info (Default is yourself)
+    #
+    # Obtain user attributes
+    #
+    # @param [String] userId
+    #    optional - numeric id (represented as a string) of user
+    # @return [Hash] user representation (string-key hash)
+    #
     def user(userId:nil)
         api = makeAPIcontext(APIInfo[:user], :GET, {userId: userId})
         return simpleAPI(api)
     end
 
-    # set the user's photo
-    # imageDataOrReadable is the raw binary image data OR
-    # an object with a read method (e.g., an open file)
-    # mimeType defaults to image/jpeg but you can specify as needed
     #
-    # NOTE: The server enforces a size limit (I don't know it)
-    #       and you will get an HTTP "Too Large" error if you exceed it
+    # Set the user's photo
+    #
+    # @note the server enforces an undocumented maximum data size.
+    #   Exceeding the limit will raise a NumerousError (HTTP 413 / Too Large)
+    # @param [String,#read] imageDataOrReadable
+    #   Either a binary-data string of the image data or an object
+    #   with a "read" method. The entire data stream will be read.
+    # @param [String] mimeType
+    #   Optional(keyword arg). Mime type.
+    # @return [Hash] updated user representation (string-key hash)
+    #
     def userPhoto(imageDataOrReadable, mimeType:'image/jpeg')
         api = makeAPIcontext(APIInfo[:user], :photo)
         mpart = { :f => imageDataOrReadable, :mimeType => mimeType }
         return simpleAPI(api, multipart: mpart)
     end
 
-    # various iterators for invoking a block on various collections.
-    # The "return self" is convention for chaining though not clear how useful
-
-    # metrics: all metrics for the given user (default is your own)
+    #
+    # All metrics for the given user (default is your own)
+    #
+    # @param [String] userId 
+    #    optional - numeric id (represented as a string) of user
+    # @yield [m] metrics
+    # @yieldparam m [Hash] String-key representation of one metric
+    # @return self
+    #
     def metrics(userId:nil, &block)
         chunkedIterator(APIInfo[:metricsCollection], { userId: userId }, block)
         return self
     end
 
-    # subscriptions: all the subscriptions for the given user
+    #
+    # All subscriptions for the given user (default is your own)
+    #
+    # @param [String] userId 
+    #    optional - numeric id (represented as a string) of user
+    # @yield [s] subscriptions
+    # @yieldparam s [Hash] String-key representation of one subscription
+    # @return self
+    #
     def subscriptions(userId:nil, &block)
         chunkedIterator(APIInfo[:subscriptions], { userId: userId }, block)
         return self
     end    
 
 
-
-    # most popular metrics ... not an iterator
+    #
+    # Obtain array of the "most popular" metrics.
+    #
+    # @note this returns the array; it is not an Enumerator
+    #
+    # @param [Fixnum] count
+    #    optional - number of metrics to return
+    # @return [Array] Array of hashes (metric string dicts). Each element 
+    #    represents a particular popular metric.
+    #
     def mostPopular(count:nil)
         api = makeAPIcontext(APIInfo[:popular], :GET, {count: count})
         return simpleAPI(api)
     end
 
-    # test/verify connectivity to the server
+    #
+    # Verify connectivity to the server
+    #
+    # @return [true] Always returns true connectivity if ok. 
+    #     Raises an exception otherwise.
+    # @raise [NumerousAuthError] Your credentials are no good.
+    # @raise [NumerousError] Other server (or network) errors.
+    #
     def ping
         ignored = user()
-        return true      # errors throw exceptions
+        return true      # errors raise exceptions
     end
 
+    #
+    # Create a brand new metric on the server.
+    #
+    # @param label [String] Required. Label for the metric.
+    # @param value [Fixnum,Float] Optional (keyword arg). Initial value.
+    # @param attrs [Hash] Optional (keyword arg). Initial attributes.
+    # @return [NumerousMetric] 
+    #
+    # @example Create a metric with label 'bozo' and set value to 17
+    #  nr = Numerous.new('nmrs_3vblahblah') 
+    #  m = nr.createMetric('bozo')
+    #  m.write(17)
+    #
+    # @example Same example using the value keyword argument.
+    #  m = nr.createMetric('bozo', value:17)
+    #
+    # @example Same example but also setting the description attribute
+    #  m = nr.createMetric('bozo', value:17, attrs:{"description" => "a clown"})
+    #
     def createMetric(label, value:nil, attrs:{})
+
         api = makeAPIcontext(APIInfo[:create], :POST)
 
         j = attrs.clone
@@ -425,29 +570,74 @@ class Numerous  < NumerousClientInternals
         return metric(v['id'])
     end
 
-    # instantiate a metric object to access a numerous metric
-    #   -- this is NOT creating a metric on the server; this is how you
-    #      access a metric that already exists
+    #
+    # Instantiate a metric object to access a metric from the server.
+    # @return [NumerousMetric] metric object
+    # @param id [String] 
+    #     Required. Metric ID (something like '2319923751024'). NOTE: If id
+    #     is bogus this will still "work" but (of course) errors will be
+    #     raised when you do something with the metric.
+    # @see #createMetric createMetric
+    # @see NumerousMetric#validate validate
+    #
     def metric(id)
         return NumerousMetric.new(id, self)
     end
 
 end
 
+#
+# == NumerousMetric
+#
+# Class for individual Numerous metrics
+#
+# You instantiate these hanging off of a particular Numerous connection:
+#    nr = Numerous.new('nmrs_3xblahblah')
+#    m = nr.metric('754623094815712984')
+#
+# For most operations the NumerousApp server returns a JSON representation
+# of the current or modified object state. This is converted to a ruby
+# Hash of <string-key, value> pairs and returned from the appropriate methods.
+# A few of the methods return only one item from the Hash (e.g., read
+# will return just the naked number unless you ask it for the entire dictionary)
+#
+# For some operations the server returns only a success/failure code.
+# In those cases there is no useful return value from the method; the 
+# method succeeds or else raises an exception (containing the failure code).
+#
+# For the collection operations the server returns a JSON array of dictionary
+# representations, possibly "chunked" into multiple request/response operations.
+# The enumerator methods (e.g., "events") implement lazy-fetch and hide 
+# the details of the chunking from you. They simply yield each individual
+# item (string-key Hash) to your block.
+#
 
 class NumerousMetric < NumerousClientInternals
+    #
+    # @!attribute [r] id
+    # @return [String] The metric ID string.
+    #
+
+    # Constructor for a NumerousMetric
+    #
+    # @param [String] id The metric ID string.
+    # @param [Numerous] nr 
+    #    The {Numerous} object that will be used to access this metric.
     def initialize(id, nr)
         @id = id
         @nr = nr
     end
-    attr_accessor :id
+    attr_reader :id
 
-    # could have just made an accessor, but I prefer it this way for this one
+    #
+    # Obtain the {Numerous} server object associated with a metric.
+    # @return [Numerous]
+    #
     def getServer()
         return @nr
     end
 
-    APIInfo = {
+    APIInfo = {                             
       # read/update/delete a metric
       metric: {
         path: '/v1/metrics/%{metricId}' ,
@@ -538,6 +728,7 @@ class NumerousMetric < NumerousClientInternals
       }
 
     }
+    private_constant :APIInfo
 
     # small wrapper to always supply the metricId substitution
     def getAPI(a, mx, args={})
@@ -545,7 +736,14 @@ class NumerousMetric < NumerousClientInternals
     end
     private :getAPI
 
-
+    #
+    # Read the current value of a metric
+    # @param [Boolean] dictionary
+    #    If true the entire metric will be returned as a string-key Hash;
+    #    else (false/default) a bare number (Fixnum or Float) is returned.
+    # @return [Fixnum|Float] if dictionary is false (or defaulted).
+    # @return [Hash] if dictionary is true.
+    #
     def read(dictionary: false)
         api = getAPI(:metric, :GET)
         v = @nr.simpleAPI(api)
@@ -555,12 +753,22 @@ class NumerousMetric < NumerousClientInternals
     # "Validate" a metric object.
     # There really is no way to do this in any way that carries much weight.
     # However, if a user gives you a metricId and you'd like to know if
-    # that actually IS a metricId, this might be useful. Realize that
-    # even a valid metric can be deleted out from under and become invalid.
+    # that actually IS a metricId, this might be useful. 
+    #
+    # @example
+    #    someId = ... get a metric ID from someone ...
+    #    m = nr.metric(someId)
+    #    if not m.validate
+    #        puts "#{someId} is not a valid metric"
+    #    end
+    #
+    # Realize that even a valid metric can be deleted asynchronously
+    # and thus become invalid after being validated by this method.
     #
     # Reads the metric, catches the specific exceptions that occur for 
     # invalid metric IDs, and returns True/False. Other exceptions mean
     # something else went awry (server down, bad authentication, etc).
+    # @return [Boolean] validity of the metric
     def validate
         begin
             ignored = read()
@@ -578,44 +786,107 @@ class NumerousMetric < NumerousClientInternals
     end
 
 
-    # define the events, stream, interactions, and subscriptions methods
-    # All have same pattern so we use some of Ruby's awesome meta hackery
-    %w(events stream interactions subscriptions).each do |w|
-        define_method(w) do | &block |
-            @nr.chunkedIterator(APIInfo[w.to_sym], {metricId:@id}, block)
-            return self
-        end
+    #
+    # So I had a really nifty %w/.each define_method hack here to generate
+    # these methods that follow a simple pattern. Then trying to figure out
+    # how to YARD document them was daunting. If it's easy someone needs to
+    # show me (I get the impression it's possible with some run time magic
+    # but it's just too hard to figure out for now). So, here we go instead...
+    #
+
+    # Enumerate the events of a metric. Events are value updates.
+    #
+    # @yield [e] events
+    # @yieldparam e [Hash] String-key representation of one metric.
+    # @return [NumerousMetric] self
+    def events(&block)
+        @nr.chunkedIterator(APIInfo[:events], {metricId:@id}, block)
+        return self
     end
 
-    # read a single event or single interaction
-    %w(event interaction).each do |w|
-        define_method(w) do | evId |
-            api = getAPI(w.to_sym, :GET, {eventID:evId})
-            return @nr.simpleAPI(api)
-        end
+    # Enumerate the stream of a metric. The stream is events and
+    # interactions merged together into a time-ordered stream.
+    #
+    # @yield [s] stream
+    # @yieldparam s [Hash] String-key representation of one stream item.
+    # @return [NumerousMetric] self
+    def stream(&block)
+        @nr.chunkedIterator(APIInfo[:stream], {metricId:@id}, block)
+        return self
+    end
+
+    # Enumerate the interactions (like/comment/error) of a metric. 
+    #
+    # @yield [i] interactions
+    # @yieldparam i [Hash] String-key representation of one interaction.
+    # @return [NumerousMetric] self
+    def interactions(&block)
+        @nr.chunkedIterator(APIInfo[:interactions], {metricId:@id}, block)
+        return self
+    end
+
+    # Enumerate the subscriptions of a metric.
+    #
+    # @yield [s] subscriptions
+    # @yieldparam s [Hash] String-key representation of one subscription.
+    # @return [NumerousMetric] self
+    def subscriptions(&block)
+        @nr.chunkedIterator(APIInfo[:subscriptions], {metricId:@id}, block)
+        return self
+    end
+
+
+    # Obtain a specific metric event from the server
+    #
+    # @param [String] eId The specific event ID
+    # @return [Hash] The string-key hash of the event
+    # @raise [NumerousError] Not found (.code will be 404)
+    #
+    def event(eId)
+        api = getAPI(:event, :GET, {eventID:eId})
+        return @nr.simpleAPI(api)
     end
 
+    # Obtain a specific metric interaction from the server
+    #
+    # @param [String] iId The specific interaction ID
+    # @return [Hash] The string-key hash of the interaction
+    # @raise [NumerousError] Not found (.code will be 404)
+    #
+    def interaction(iId)
+        api = getAPI(:interaction, :GET, {item:iId})
+        return @nr.simpleAPI(api)
+    end
 
-    # This is an individual subscription -- namely, yours.
-    # normal users can never see anything other than their own
-    # subscription so there is really no point in ever supplying
-    # the userId parameter (the default is all you can ever use)
+    # Obtain your subscription parameters on a given metric
+    #
+    # Note that normal users cannot see other user's subscriptions.
+    # Thus the "userId" parameter is somewhat pointless; you can only 
+    # ever see your own.
+    # @param [String] userId
+    # @return [Hash] your subscription attributes
     def subscription(userId=nil)
         api = getAPI(:subscription, :GET, {userId: userId})
         return @nr.simpleAPI(api)
     end
 
-    # Subscribe to a metric. See the API docs for what should be
+    # Subscribe to a metric. 
+    #
+    # See the NumerousApp API docs for what should be
     # in the dict. This function will fetch the current parameters
     # and update them with the ones you supply (because the server
     # does not like you supplying an incomplete dictionary here).
-    # While in some cases this might be a bit of extra overhead
-    # it doesn't really matter because how often do you do this...
-    # You can, however, stop that with overwriteAll=True
+    # You can prevent the fetch/merge via overwriteAll:true
     #
-    # NOTE that you really can only subscribe yourself, so there
-    #      really isn't much point in specifying a userId 
-    def subscribe(dict, userId:nil, overwriteAll:False)
+    # Normal users cannot set other user's subscriptions.
+    # @param [Hash] dict
+    #   string-key hash of subscription parameters
+    # @param [String] userId
+    #   Optional (keyword arg). UserId to subscribe.
+    # @param [Boolean] overwriteAll
+    #   Optional (keyword arg). If true, dict is sent without reading
+    #   the current parameters and merging them.
+    def subscribe(dict, userId:nil, overwriteAll:false)
         if overwriteAll
             params = {}
         else
@@ -628,12 +899,33 @@ class NumerousMetric < NumerousClientInternals
         return @nr.simpleAPI(api, jdict:params)
     end
 
-    # write a value to a metric.
+    # Write a value to a metric.
+    #
+    # @param [Fixnum|Float] newval Required. Value to be written.
+    #
+    # @param [Boolean] onlyIf 
+    #   Optional (keyword arg). Only creates an event at the server
+    #   if the newval is different from the current value. Raises
+    #   NumerousMetricConflictError if there is no change in value.
+    #   WARNING: Not atomic at the server; it is still possible to get
+    #   a success code result from this even if your value was already 
+    #   the current value (under simultaneous-update scenarios).
+    #
+    # @param [Boolean] add
+    #   Optional (keyword arg). Sends the "action: ADD"	attribute which
+    #   causes the server to ADD newval to the current metric value.
+    #   WARNING: As of Dec 2014 there is still a bug in the server that
+    #   causes ADD operations to not be atomic. Until that bug is fixed
+    #   the semantics of ADD are no different than if you did a read/write
+    #   (as two separate operations) yourself.
+    # @param [Boolean] dictionary
+    #   If true the entire metric will be returned as a string-key Hash;
+    #   else (false/default) the bare number (Fixnum or Float) for the
+    #   resulting new value is returned.
+    # @return [Fixnum|Float] if dictionary is false (or defaulted). The new
+    #   value of the metric is returned as a bare number.
+    # @return [Hash] if dictionary is true the entire new metric is returned.
     #
-    #   onlyIf=true sends the "only if it changed" feature of the NumerousAPI.
-    #      -- throws NumerousMetricConflictError if no change
-    #   add=true sends the "action: ADD" (the value is added to the metric)
-    #   dictionary=true returns the full dictionary results.
     def write(newval, onlyIf:false, add:false, dictionary:false)
         j = { 'value' => newval }
         if onlyIf
@@ -651,7 +943,7 @@ class NumerousMetric < NumerousClientInternals
             # if onlyIf was specified and the error is "conflict"
             # (meaning: no change), raise ConflictError specifically
             if onlyIf and e.code == 409
-                raise NumerousMetricConflictError.new(e.details, 0, "No Change")
+                raise NumerousMetricConflictError.new("No Change", 0, e.details)
             else
                 raise e        # never mind, plain NumerousError is fine
             end
@@ -660,6 +952,20 @@ class NumerousMetric < NumerousClientInternals
         return (if dictionary then v else v['value'] end)
     end
 
+    # Update parameters of a metric (such as "description", "label", etc).
+    # Not to be used (won't work) to update a metric's value.
+    #
+    # @param [Hash] dict
+    #   string-key Hash of the parameters to be updated.
+    # @param [Boolean] overwriteAll
+    #   Optional (keyword arg). If false (default), this method will first
+    #   read the current metric parameters from the server and merge them
+    #   with your updates before writing them back. If true your supplied
+    #   dictionary will become the entirety of the metric's parameters, and
+    #   any parameters you did not include in your dictionary will revert to
+    #   their default values. 
+    # @return [Hash] string-key Hash of the new metric parameters.
+    #
     def update(dict, overwriteAll:false)
         newParams = (if overwriteAll then {} else read(dictionary:true) end)
         dict.each { |k, v| newParams[k] = v }
@@ -679,6 +985,8 @@ class NumerousMetric < NumerousClientInternals
     #
     # "Like" a metric
     #
+    # @return [String] The ID of the resulting interaction (the "like")
+    #
     def like
         # a like is written as an interaction
         return writeInteraction({ 'kind' => 'like' })
@@ -687,6 +995,9 @@ class NumerousMetric < NumerousClientInternals
     #
     # Write an error to a metric
     #
+    # @param [String] errText The error text to write.
+    # @return [String] The ID of the resulting interaction (the "error")
+    #
     def sendError(errText)
         # an error is written as an interaction thusly:
         # (commentBody is used for the error text)
@@ -695,7 +1006,10 @@ class NumerousMetric < NumerousClientInternals
     end
 
     #
-    # Simply comment on a metric
+    # Comment on a metric
+    #
+    # @param [String] ctext The comment text to write.
+    # @return [String] The ID of the resulting interaction (the "comment")
     #
     def comment(ctext)
         j = { 'kind' => 'comment' , 'commentBody' => ctext }
@@ -703,50 +1017,68 @@ class NumerousMetric < NumerousClientInternals
     end
 
     # set the background image for a metric
-    # imageDataOrReadable is the raw binary image data OR
-    # an object with a read method (e.g., an open file)
-    # mimeType defaults to image/jpeg but you can specify as needed
+    # @note the server enforces an undocumented maximum data size.
+    #   Exceeding the limit will raise a NumerousError (HTTP 413 / Too Large)
+    # @param [String,#read] imageDataOrReadable
+    #   Either a binary-data string of the image data or an object
+    #   with a "read" method. The entire data stream will be read.
+    # @param [String] mimeType
+    #   Optional(keyword arg). Mime type.
+    # @return [Hash] updated metric representation (string-key hash)
     #
-    # NOTE: The server enforces a size limit (I don't know it)
-    #       and you will get an HTTP "Too Large" error if you exceed it
     def photo(imageDataOrReadable, mimeType:'image/jpeg')
         api = getAPI(:photo, :POST)
         mpart = { :f => imageDataOrReadable, :mimeType => mimeType }
         return @nr.simpleAPI(api, multipart: mpart)
     end
 
-    # various deletion methods.
-    # NOTE: If you try to delete something that isn't there, you will
-    #       see an exception but the "error" code will be 200/OK.
-    # Semantically, the delete "works" in that case (i.e., the invariant
-    # that the thing should be gone after this invocation is, in fact, true). 
-    # Nevertheless, I let the exception come through to you in case you 
-    # want to know if this happened. This note applies to all deletion methods.
-
+    # Delete the metric's photo
+    # @note Deleting a photo that isn't there will raise a NumerousError
+    #   but the error code will be 200/OK.
+    # @return [nil]
     def photoDelete
         api = getAPI(:photo, :DELETE)
         v = @nr.simpleAPI(api)
         return nil
     end
 
+    # Delete an event (a value update)
+    # @note Deleting an event that isn't there will raise a NumerousError
+    #   but the error code will be 200/OK.
+    # @param [String] evID ID (string) of the event to be deleted.
+    # @return [nil]
     def eventDelete(evID)
         api = getAPI(:event, :DELETE, {eventID:evID})
         v = @nr.simpleAPI(api)
         return nil
     end
 
+    # Delete an interaction (a like/comment/error)
+    # @note Deleting an interaction that isn't there will raise a NumerousError
+    #   but the error code will be 200/OK.
+    # @param [String] interID ID (string) of the interaction to be deleted.
+    # @return [nil]
     def interactionDelete(interID)
         api = getAPI(:interaction, :DELETE, {item:interID})
         v = @nr.simpleAPI(api)
         return nil
     end
 
-    # the photoURL returned by the server in the metrics parameters
-    # still requires authentication to fetch (it then redirects to the "real"
+    # Obtain the underlying photoURL for a metric.
+    #
+    # The photoURL is available in the metrics parameters so you could 
+    # just read(dictionary:true) and obtain it that way. However this goes
+    # one step further ... the URL in the metric itself still requires 
+    # authentication to fetch (it then redirects to the "real" underlying
     # static photo URL). This function goes one level deeper and
-    # returns you an actual, publicly-fetchable, photo URL. I have not
-    # yet figured out how to tease this out without doing the full-on GET
-    # (using HEAD on a photo is rejected by the server)
+    # returns you an actual, publicly-fetchable, photo URL.
+    #
+    # IMPLEMENTATION NOTE: Fetches (and discards) the entire underlying photo,
+    # because that was the easiest way to tease out the target URL from
+    # the Net:HTTP library.
+    #
+    # @return [String, nil] URL. If there is no photo returns nil.
+    #
     def photoURL
         v = read(dictionary:true)
         begin
@@ -762,17 +1094,27 @@ class NumerousMetric < NumerousClientInternals
     # some convenience functions ... but all these do is query the
     # server (read the metric) and return the given field... you could
     # do the very same yourself. So I only implemented a few useful ones.
+
+    # Get the label of a metric.
+    #
+    # @return [String] The metric label.
     def label
         v = read(dictionary:true)
         return v['label']
     end
 
+    # Get the URL for the metric's web representation
+    #
+    # @return [String] URL.
     def webURL
         v = read(dictionary:true)
         return v['links']['web']
     end
 
-    # be 100% sure, because this cannot be undone. Deletes a metric
+    # Delete a metric (permanently). Be 100% you want this, because there
+    # is absolutely no undo.
+    #
+    # @return [nil]
     def crushKillDestroy
         api = getAPI(:metric, :DELETE)
         v = @nr.simpleAPI(api)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: numerousapp
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Neil Webber
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-23 00:00:00.000000000 Z
+date: 2014-12-24 00:00:00.000000000 Z
 dependencies: []
 description: Classes implementing the NumerousApp REST APIs for metrics. Requires
   Ruby 2.x
@@ -43,3 +43,4 @@ signing_key:
 specification_version: 4
 summary: NumerousApp API
 test_files: []
+has_rdoc: