identifier.rb in ezid-client-0.4.1

- old
+ new

@@ -1,25 +1,35 @@
 module Ezid
+  #
+  # Represents an EZID identifier as a resource.
+  #
+  # @api public
+  #
   class Identifier
 
     attr_reader :id, :client
     attr_accessor :shoulder, :metadata
 
+    # Attributes to display on inspect
     INSPECT_ATTRS = %w( id status target created )
 
+    # EZID status terms
     PUBLIC = "public"
     RESERVED = "reserved"
     UNAVAILABLE = "unavailable"
 
     class << self
+      # Creates or mints an identifier (depending on arguments)
+      # @see #save
       # @return [Ezid::Identifier] the new identifier
       # @raise [Ezid::Error]
       def create(attrs = {})
         identifier = new(attrs)
         identifier.save
       end
 
+      # Retrieves an identifier
       # @return [Ezid::Identifier] the identifier
       # @raise [Ezid::Error] if the identifier does not exist in EZID
       def find(id)
         identifier = new(id: id)
         identifier.reload
@@ -29,11 +39,11 @@
     def initialize(args={})
       @client = args.delete(:client) || Client.new
       @id = args.delete(:id)
       @shoulder = args.delete(:shoulder)
       @metadata = Metadata.new(args.delete(:metadata))
-      update_attributes(args)
+      update_metadata(args)
       @deleted = false
     end
 
     def inspect
       attrs = if deleted?
@@ -63,12 +73,16 @@
         create_or_mint
       end
       reload
     end
 
-    def update_attributes(attrs={})
+    # Updates the metadata 
+    # @param attrs [Hash] the metadata
+    # @return [Ezid::Identifier] the identifier
+    def update_metadata(attrs={})
       attrs.each { |k, v| send("#{k}=", v) }
+      self
     end
 
     # Is the identifier persisted?
     # @return [Boolean]
     def persisted?
@@ -80,61 +94,73 @@
     # @return [Boolean]
     def deleted?
       @deleted
     end
 
+    # Updates the metadata and saves the identifier
+    # @param data [Hash] a hash of metadata
     # @return [Ezid::Identifier] the identifier
     # @raise [Ezid::Error]
-    def update(data)
-      metadata.update(data)
+    def update(data={})
+      update_metadata(data)
       save
     end
 
+    # Reloads the metadata from EZID (local changes will be lost!)
     # @return [Ezid::Identifier] the identifier
     # @raise [Ezid::Error]
     def reload
       refresh_metadata
       self
     end
 
-    # Empties the (local) metadata
+    # Empties the (local) metadata (changes will be lost!)
     # @return [Ezid::Identifier] the identifier
     def reset
       clear_metadata
       self
     end
 
+    # Deletes the identifier from EZID
     # @return [Ezid::Identifier] the identifier
     # @raise [Ezid::Error]
     def delete
       raise Error, "Status must be \"reserved\" to delete (status: \"#{status}\")." unless reserved?
       client.delete_identifier(id)
       @deleted = true
       reset
     end
 
-    def method_missing(name, *args)
-      return metadata.send(name, *args) if metadata.respond_to?(name)
-      super
-    end
-
+    # Is the identifier reserved?
+    # @return [Boolean]
     def reserved?
       status == RESERVED
     end
 
+    # Is the identifier public?
+    # @return [Boolean]
     def public?
       status == PUBLIC
     end
 
+    # Is the identifier unavailable?
+    # @return [Boolean]
     def unavailable?
       status == UNAVAILABLE
     end
 
+    protected
+
+    def method_missing(name, *args)
+      return metadata.send(name, *args) if metadata.respond_to?(name)
+      super
+    end
+
     private
 
     def refresh_metadata
       response = client.get_identifier_metadata(id)
-      @metadata.replace(response.metadata)
+      @metadata = Metadata.new(response.metadata)
     end
 
     def clear_metadata
       @metadata.clear
     end