active-triples 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ac814924c8de3fbbc7c606f086d17dbaae387fc9
-  data.tar.gz: 80686fffd9084847077ffd12167279ee7becb17e
+  metadata.gz: c8f2271397f8aecc1c96f8bd3cf63744e87e0989
+  data.tar.gz: 25d4b23e7404fafd3c437e4cf0ff4de54f9c7c54
 SHA512:
-  metadata.gz: f81545cb8bd68a532d67ea52a4d0b011be195c76af069d77e2f4a21d012c76a3a853819e9ebc7745918561dd67fad6bab40589173eb2219e915d80aa20e6429c
-  data.tar.gz: 590fedb6315223dfb2485415c8d345dc8928f2cadf0b5c36ca3675d50b067cc32a0843a1cb89af24749eea81691d7f0f881f14716c9caac7069e05cbd43b16b5
+  metadata.gz: b4645aa5fc8dd320fe19fe46268b500533fad11836093dcd8ad594b7b9052f5f531e61332b625a4284ebae92b8de2651ca29e8aa0c9833b5a5a0a9e635a3a75a
+  data.tar.gz: fed0f9f047b36fd5f84bb231e83f021da0aa27991239697b58c173df75685b4a30a4a5715095cf538d709fd4c4336debf93b1814df0b73d0be0a3fc11a01becf

data/AUTHORS

@@ -1,2 +1,2 @@
-Tom Johnson (thomas.johnson@oregonstate.edu)
-Trey Terrell
+* Tom Johnson (thomas.johnson@oregonstate.edu)
+* Trey Terrell

data/Guardfile

@@ -0,0 +1,9 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/README.md

@@ -1,38 +1,152 @@
-ActiveTriples
-==============
+Description
+-----------
 
 [![Build Status](https://travis-ci.org/no-reply/ActiveTriples.png?branch=master)](https://travis-ci.org/no-reply/ActiveTriples)
 
-Modeling RDF graphs in Ruby.
+An ActiveModel-like interface for RDF data. Models graphs as Resources with property/attribute configuration, accessors, and other methods to support Linked Data in a Ruby/Rails enviornment.
+
+This library was extracted from work on [ActiveFedora](https://github.com/projecthydra/active_fedora). It is closely related to (and borrows some syntax from) [Spira](https://github.com/ruby-rdf/spira), but does some important things differently.
+
+Installation
+------------
+
+Add `gem "active-triples"` to your Gemfile and run `bundle`.
+
+Or install manually with `gem install active-triples`.
+
+Defining Resource Models
+------------------------
+
+The core class of ActiveTriples is ActiveTriples::Resource. You can subclass this to create ActiveModel-like classes that represent a node in an RDF graph, and its surrounding statements. Resources implement all the functionality of an RDF::Graph. You can manipulate them by adding or deleting statements, query, serialize, and load arbitrary RDF. 
 
-How to Use
------------
 
 ```ruby
 class Thing < ActiveTriples::Resource
   configure :type => RDF::OWL.Thing, :base_uri => 'http://example.org/things#'
   property :title, :predicate => RDF::DC.title
   property :description, :predicate => RDF::DC.description
-  property :creator, :predicate => RDF::DC.creator, :class_name => 'Person'
 end
 
 obj = Thing.new('123')
 obj.title = 'Resource'
-obj.description = 'A resource in an RDF graph.'
+obj.description = 'A resource.'
+obj.dump :ntriples # => "<http://example.org/things#123> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#Thing> .\n<http://example.org/things#123> <http://purl.org/dc/terms/title> \"Resource\" .\n<http://example.org/things#123> <http://purl.org/dc/terms/description> \"A resource.\" .\n"
+```
+URI and bnode values are built out as Resources when accessed, and a model class can be configured on individual properties.
 
-obj.dump :ntriples
-# => "<http://example.org/things#123> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#Thing> .\n<http://example.org/things#123> <http://purl.org/dc/terms/title> \"Resource\" .\n<http://example.org/things#123> <http://purl.org/dc/terms/description> \"A resource in an RDF graph.\" .\n"
+```ruby
+Thing.property :creator, :predicate => RDF::DC.creator, :class_name => 'Person'
 
 class Person < ActiveTriples::Resource
   configure :type => RDF::FOAF.Person, :base_uri => 'http://example.org/people#'
   property :name, :predicate => RDF::FOAF.name
 end
 
-obj.creator = Person.new
-obj.creator
+obj_2 = Thing.new('2')
+obj_2.creator = Person.new
+obj_2.creator
 # => [#<Person:0x3fbe84ac9234(default)>]
 
-obj.creator.first.name = 'Herman Melville'
-obj.dump :ntriples
-# => "<http://example.org/things#123> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#Thing> .\n<http://example.org/things#123> <http://purl.org/dc/terms/title> \"Resource\" .\n<http://example.org/things#123> <http://purl.org/dc/terms/description> \"A resource in an RDF graph.\" .\n<http://example.org/things#123> <http://purl.org/dc/terms/creator> _:g70087502237940 .\n_:g70087502237940 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .\n"
-```
+obj_2.creator.first.name = 'Herman Melville'
+obj_2.dump :ntriples # => "<http://example.org/things#2> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#Thing> .\n<http://example.org/things#2> <http://purl.org/dc/terms/creator> _:g70263220218800 .\n_:g70263220218800 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .\n_:g70263220218800 <http://xmlns.com/foaf/0.1/name> \"Herman Melville\" .\n"
+```
+
+Open Model
+-----------
+
+A Resource lets you handle data as a graph, independent of whether it is defined in the model. This is important for working in a Linked Data context, where you will want access to data you may not have known about when your models were written.
+
+```ruby
+related = Thing.new
+
+related << RDF::Statement(related, RDF::DC.relation, obj)
+related << RDF::Statement(related, RDF::DC.subject, 'ActiveTriples')
+	
+related.query(:subject => related, :predicate => RDF::DC.relation).each_statement {|s,p,o| puts o}
+# => http://example.org/things#123
+related.query(:subject => subject, :predicate => RDF::DC.relation).each_statement {|s,p,o| puts o}
+# => http://example.org/things#123
+```
+
+Any operation you can run against an RDF::Graph works with Resources, too. Or you can use generic setters and getters with URI predicates:
+
+```ruby
+related.set_value(RDF::DC.relation, obj) 
+related.set_value(RDF::DC.subject, 'ActiveTriples')
+
+related.get_values(RDF::DC.relation) # => [#<Thing:0x3f949c6a2294(default)>]
+related.get_values(RDF::DC.subject) # => ["ActiveTriples"]
+```
+
+Some convienience methods provide support for handling data from web sources:
+  * `fetch` loads data from the Resource's #rdf_subject URI
+  * `rdf_label` queries across common (& configured) label fields and returning the best match
+
+```ruby
+require 'linkeddata' # to support various serializations
+
+osu = ActiveTriples::Resource.new 'http://dbpedia.org/resource/Oregon_State_University'
+osu.fetch
+
+osu.rdf_label => => ["Oregon State University", "Oregon State University", "Université d'État de l'Oregon", "Oregon State University", "Oregon State University", "オレゴン州立大学", "Universidad Estatal de Oregón", "Oregon State University", "俄勒岡州立大學", "Universidade do Estado do Oregon"]
+```
+
+Typed Data
+-----------
+
+Typed literals are handled natively through Ruby types and [RDF::Literal](https://github.com/ruby-rdf/rdf/tree/develop/lib/rdf/model/literal). There is no need to register a specific type for a property, simply pass the setter the appropriate typed data. See the examples in the RDF::Literal documentation for futher information about supported datatypes.
+
+```ruby
+Thing.property :date, :predicate => RDF::DC.date
+
+my_thing = Thing.new
+my_thing.date = Date.today
+
+puts my_thing.dump :ntriples
+# _:g70072864570340 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#Thing> .
+# _:g70072864570340 <http://purl.org/dc/terms/date> "2014-06-19Z"^^<http://www.w3.org/2001/XMLSchema#date> .
+```
+
+Data is cast back to the appropriate class when it is accessed.
+
+```ruby
+my_thing.date
+# => [Thu, 19 Jun 2014]
+```
+   
+Note that you can mix types on a single property.
+
+```ruby     
+my_thing.date << DateTime.now
+my_thing.date << "circa 2014"
+my_thing.date
+# => [Thu, 19 Jun 2014, Thu, 19 Jun 2014 11:39:21 -0700, "circa 2014"]
+
+puts my_thing.dump :ntriples
+# _:g70072864570340 <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/2002/07/owl#Thing> .
+# _:g70072864570340 <http://purl.org/dc/terms/date> "2014-06-19Z"^^<http://www.w3.org/2001/XMLSchema#date> .
+# _:g70072864570340 <http://purl.org/dc/terms/date> "2014-06-19T11:39:21-07:00"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
+# _:g70072864570340 <http://purl.org/dc/terms/date> "circa 2014" .
+```
+
+Repositories and Persistence
+-----------------------------
+
+Contributing
+-------------
+
+Please observe the following guidelines:
+
+ - Do your work in a feature branch based on ```master``` and rebase before submitting a pull request.
+ - Write tests for your contributions.
+ - Document every method you add using YARD annotations. (_Note: Annotations are sparse in the existing codebase, help us fix that!_)
+ - Organize your commits into logical units.
+ - Don't leave trailing whitespace (i.e. run ```git diff --check``` before committing).
+ - Use [well formed](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) commit messages.
+
+By contributing to ActiveTriples, you agree to dedicate all copyright interest over submitted work to the public domain (see the included ```WAIVER``` and ```LICENSE``` files). For substantial contributions, you may be asked to submit a formal disclaimer of your (and/or your employer's) copyright interest in the software.
+
+License
+--------
+
+This is free and unencumbered public domain software. For more information, see http://unlicense.org/ or the accompanying ```LICENSE``` file.

data/WAIVER

@@ -0,0 +1,5 @@
+I dedicate any and all copyright interest in this software to the
+public domain. I make this dedication for the benefit of the public at
+large and to the detriment of my heirs and successors. I intend this
+dedication to be an overt act of relinquishment in perpetuity of all
+present and future rights to this software under copyright law.

data/active-triples.gemspec

@@ -22,8 +22,10 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency('rdoc')
   s.add_development_dependency('rspec')
+  s.add_development_dependency('guard-rspec')
   s.add_development_dependency('webmock')
   s.add_development_dependency('nokogiri')
+  s.add_development_dependency('pragmatic_context', '~> 0.1.2')
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {spec}/*`.split("\n")

data/lib/active_triples/configurable.rb

@@ -8,7 +8,7 @@ module ActiveTriples
   #
   # Define properties at the class level with:
   #
-  #    configure base_uri: "http://oregondigital.org/resource/", repository: :parent
+  #    configure base_uri: "http://oregondigital.org/resource/", repository: :default
   # Available properties are base_uri, rdf_label, type, and repository
   module Configurable
     extend Deprecation
@@ -25,6 +25,8 @@ module ActiveTriples
       nil
     end
 
+    ##
+    # @deprecated use `configure type:` instead.
     def rdf_type(value)
       Deprecation.warn Configurable, "rdf_type is deprecated and will be removed in active-fedora 8.0.0. Use configure type: instead.", caller
       configure type: value
@@ -34,8 +36,21 @@ module ActiveTriples
       :parent
     end
 
-    # API method for configuring class properties an RDF Resource may need.
-    # This is an alternative to overriding the methods extended with this module.
+    ##
+    # API for configuring class properties on a Resource. This is an 
+    # alternative to overriding the methods in this module.
+    #
+    # Can configure the following values:
+    #  - base_uri (allows passing slugs to the Resource initializer 
+    #    in place of fully qualified URIs)
+    #  - rdf_label (overrides default label predicates)
+    #  - type (a default rdf:type to include when initializing a
+    #    new Resource)
+    #  - repository (the target persist location to for the Resource)
+    # 
+    #   configure base_uri: "http://oregondigital.org/resource/", repository: :default
+    #
+    # @param options [Hash]
     def configure(options = {})
       {
         base_uri: options[:base_uri],

data/lib/active_triples/list.rb

@@ -110,6 +110,13 @@ module ActiveTriples
         super
       end
 
+      protected
+      # Clear out any old assertions in the repository about this node or statement
+      # thus preparing to receive the updated assertions.
+      def erase_old_resource
+        RDF::List.new(rdf_subject, repository).clear
+      end
+
       private
         def attributes_to_list(value, klass)
           value.each do |entry|

data/lib/active_triples/node_config.rb

@@ -16,6 +16,7 @@ module ActiveTriples
     end
 
     def class_name
+      raise "class_name for #{term} is a #{@class_name.class}; must be a class" unless @class_name.kind_of? Class or @class_name.kind_of? String
       if @class_name.kind_of?(String)
         begin
           new_class = @class_name.constantize

data/lib/active_triples/properties.rb

@@ -1,4 +1,3 @@
-require 'deprecation'
 require 'active_support/core_ext/hash'
 
 module ActiveTriples
@@ -11,15 +10,7 @@ module ActiveTriples
   #
   #    property :title, predicate: RDF::DC.title, class_name: ResourceClass
   #
-  # or with the 'old' style:
-  #
-  #    map_predicates do |map|
-  #      map.title(in: RDF::DC)
-  #    end
-  #
-  # You can pass a block to either to set index behavior.
   module Properties
-    extend Deprecation
     attr_accessor :config
 
     ##
@@ -35,6 +26,11 @@ module ActiveTriples
       register_property(name)
     end
 
+    ##
+    # Returns the properties registered to the class and their 
+    # configurations.
+    #
+    # @return [ActiveSupport::HashWithIndifferentAccess{String => ActiveTriples::NodeConfig}]
     def config
       @config ||= if superclass.respond_to? :config
         superclass.config.dup
@@ -46,11 +42,23 @@ module ActiveTriples
     alias_method :properties, :config
     alias_method :properties=, :config=
 
+    ##
+    # Given a property name or a predicate, return the configuration
+    # for the matching property.
+    #
+    # @param term [#to_sym, RDF::Resource] a property name to predicate
+    #
+    # @return [ActiveTriples::NodeConfig]
     def config_for_term_or_uri(term)
       return config[term.to_sym] unless term.kind_of? RDF::Resource
       config.each { |k, v| return v if v.predicate == term.to_uri }
     end
 
+    ##
+    # List the property names registered to the class.
+    #
+    # @return [Array<Symbol>] list of the symbolized names of registered
+    #   properties
     def fields
       properties.keys.map(&:to_sym)
     end
@@ -59,7 +67,9 @@ module ActiveTriples
 
     ##
     # Private method for creating accessors for a given property.
-    # @param [#to_s] name Name of the accessor to be created, get/set_value is called on the resource using this.
+    #
+    # @param [#to_s] name Name of the accessor to be created, 
+    #   get/set_value is called on the resource using this.
     def register_property(name)
       parent = Proc.new{self}
       # parent = Proc.new{resource} if self < ActiveFedora::Datastream
@@ -70,27 +80,5 @@ module ActiveTriples
         instance_eval(&parent).get_values(name.to_sym)
       end
     end
-
-    public
-    # Mapper is for backwards compatibility with ActiveFedora::RDFDatastream
-    class Mapper
-      attr_accessor :parent
-      def initialize(parent)
-        @parent = parent
-      end
-      def method_missing(name, *args, &block)
-        properties = args.first || {}
-        vocab = properties.delete(:in)
-        to = properties.delete(:to) || name
-        predicate = vocab.send(to)
-        parent.property(name, properties.merge(predicate: predicate), &block)
-      end
-    end
-    def map_predicates
-      Deprecation.warn Properties, "map_predicates is deprecated and will be removed in active-fedora 8.0.0. Use property :name, predicate: predicate instead.", caller
-      mapper = Mapper.new(self)
-      yield(mapper)
-    end
-
   end
 end

data/lib/active_triples/resource.rb

@@ -24,8 +24,7 @@ module ActiveTriples
     extend Configurable
     extend Properties
     extend Deprecation
-    extend ActiveModel::Naming
-    include ActiveModel::Conversion
+    include ActiveModel::Model
     include ActiveModel::Serialization
     include ActiveModel::Serializers::JSON
     include NestedAttributes
@@ -37,13 +36,23 @@ module ActiveTriples
       end
 
       ##
-      # Adapter for a consistent interface for creating a new node from a URI.
-      # Similar functionality should exist in all objects which can become a node.
+      # Adapter for a consistent interface for creating a new Resource 
+      # from a URI. Similar functionality should exist in all objects 
+      # which can become a Resource.
+      #
+      # @param uri [#to_uri, String]
+      # @param vals values to pass as arguments to ::new
+      #
+      # @return [ActiveTriples::Resource] a Resource with  
       def from_uri(uri,vals=nil)
         new(uri, vals)
       end
     end
 
+    ##
+    # Specifies whether the object is currently writable.
+    #
+    # @return [true, false] 
     def writable?
       !frozen?
     end
@@ -68,8 +77,14 @@ module ActiveTriples
       self.get_values(:type) << self.class.type if self.class.type.kind_of?(RDF::URI) && type.empty?
     end
 
+    ##
+    # Returns the current object.
+    #
+    # @deprecated redundant, simply returns self. 
+    # 
+    # @return [self]
     def graph
-      Deprecation.warn Resource, "graph is redundant & deprecated. It will be removed in active-fedora 8.0.0.", caller
+      Deprecation.warn Resource, "graph is redundant & deprecated. It will be removed in ActiveTriples 0.2.0.", caller
       self
     end
 
@@ -112,28 +127,51 @@ module ActiveTriples
         end
       end
     end
+    
+    ##
+    # Returns a serialized string representation of self.
+    # Extends the base implementation builds a JSON-LD context if the
+    # specified format is :jsonld and a context is provided by 
+    # #jsonld_context
+    # 
+    # @see RDF::Enumerable#dump
+    #
+    # @param args [Array<Object>] 
+    # @return [String]
+    def dump(*args)
+      if args.first == :jsonld and respond_to?(:jsonld_context)
+        args << {} unless args.last.is_a?(Hash) 
+        args.last[:context] ||= jsonld_context
+      end
+      super
+    end
 
+    ##
+    # @return [RDF::URI, RDF::Node] a URI or Node which the resource's
+    #   properties are about.
     def rdf_subject
       @rdf_subject ||= RDF::Node.new
     end
-
+    alias_method :to_term, :rdf_subject
+    
+    ##
+    # A string identifier for the resource
     def id
       node? ? nil : rdf_subject.to_s
     end
-
+    
     def node?
       return true if rdf_subject.kind_of? RDF::Node
       false
     end
 
-    def to_term
-      rdf_subject
-    end
-
+    ##
+    # @return [String, nil] the base URI the resource will use when
+    #   setting its subject. `nil` if none is used.
     def base_uri
       self.class.base_uri
     end
-
+    
     def type
       self.get_values(:type).to_a.map{|x| x.rdf_subject}
     end
@@ -144,8 +182,8 @@ module ActiveTriples
     end
 
     ##
-    # Look for labels in various default fields, prioritizing
-    # configured label fields
+    # Looks for labels in various default fields, prioritizing
+    # configured label fields.
     def rdf_label
       labels = Array(self.class.rdf_label)
       labels += default_labels
@@ -156,12 +194,26 @@ module ActiveTriples
       node? ? [] : [rdf_subject.to_s]
     end
 
+    ##
+    # Lists fields registered as properties on the object.
+    #
+    # @return [Array<Symbol>] the list of registered properties.
     def fields
       properties.keys.map(&:to_sym).reject{|x| x == :type}
     end
 
     ##
-    # Load data from URI
+    # Load data from the #rdf_subject URI. Retrieved data will be 
+    # parsed into the Resource's graph from available RDF::Readers
+    # and available from property accessors if if predicates are 
+    # registered.
+    # 
+    #    osu = ActiveTriples::Resource.new('http://dbpedia.org/resource/Oregon_State_University')
+    #    osu.fetch
+    #    osu.rdf_label.first
+    #    # => "Oregon State University"
+    # 
+    # @return [ActiveTriples::Resource] self
     def fetch
       load(rdf_subject)
       self
@@ -169,16 +221,16 @@ module ActiveTriples
 
     def persist!
       raise "failed when trying to persist to non-existant repository or parent resource" unless repository
-      repository.delete [rdf_subject,nil,nil] unless node?
-      if node?
-        repository.statements.each do |statement|
-          repository.send(:delete_statement, statement) if statement.subject == rdf_subject
-        end
-      end
+      erase_old_resource
       repository << self
       @persisted = true
     end
 
+    ##
+    # Indicates if the resource is persisted.
+    #
+    # @see #persist
+    # @return [true, false]
     def persisted?
       @persisted ||= false
       return (@persisted and parent.persisted?) if parent
@@ -187,6 +239,8 @@ module ActiveTriples
 
     ##
     # Repopulates the graph from the repository or parent resource.
+    #
+    # @return [true, false]
     def reload
       @term_cache ||= {}
       if self.class.repository == :parent
@@ -280,6 +334,10 @@ module ActiveTriples
     end
     alias_method :destroy!, :destroy
     
+    ##
+    # Indicates if the Resource has been destroyed.
+    # 
+    # @return [true, false]
     def destroyed?
       @destroyed ||= false
     end
@@ -290,12 +348,16 @@ module ActiveTriples
       end
     end
 
+    ##
+    # Indicates if the record is 'new' (has not yet been persisted).
+    #
+    # @return [true, false]
     def new_record?
       not persisted?
     end
 
     ##
-    # @return [String] the string to index in solr
+    # @return [String] the string representation of the resource
     def solrize
       node? ? rdf_label : rdf_subject.to_s
     end
@@ -308,22 +370,57 @@ module ActiveTriples
       @marked_for_destruction
     end
 
-    private
+    protected
+
+      #Clear out any old assertions in the repository about this node or statement
+      # thus preparing to receive the updated assertions.
+      def erase_old_resource
+        if node?
+          repository.statements.each do |statement|
+            repository.send(:delete_statement, statement) if statement.subject == rdf_subject
+          end
+        else
+          repository.delete [rdf_subject, nil, nil]
+        end
+     end
 
+    private
+    
+      ##
+      # Returns the properties registered and their configurations.
+      #
+      # @return [ActiveSupport::HashWithIndifferentAccess{String => ActiveTriples::NodeConfig}]
       def properties
         self.singleton_class.properties
       end
 
+      ##
+      # List of RDF predicates registered as properties on the object.
+      #
+      # @return [Array<RDF::URI>]
       def registered_predicates 
         properties.values.map { |config| config.predicate }
       end
       
+      ##
+      # List of RDF predicates used in the Resource's triples, but not
+      # mapped to any property or accessor methods.
+      #
+      # @return [Array<RDF::URI>]
       def unregistered_predicates
         preds = registered_predicates
         preds << RDF.type
         predicates.select { |p| !preds.include? p }
       end
 
+      ##
+      # Given a predicate which has been registered to a property, 
+      # returns the name of the matching property.
+      #
+      # @param predicate [RDF::URI]
+      #
+      # @return [String, nil] the name of the property mapped to the 
+      #   predicate provided
       def property_for_predicate(predicate)
         properties.each do |property, values|
           return property if values[:predicate] == predicate
@@ -342,6 +439,9 @@ module ActiveTriples
       ##
       # Return the repository (or parent) that this resource should
       # write to when persisting.
+      #
+      # @return [RDF::Repository, ActiveTriples::Resource] the target
+      #   repository
       def repository
         @repository ||= 
           if self.class.repository == :parent
@@ -352,10 +452,22 @@ module ActiveTriples
       end
 
       ##
-      # Takes a URI or String and aggressively tries to create a valid RDF URI.
-      # Combines the input with base_uri if appropriate.
+      # Takes a URI or String and aggressively tries to convert it into
+      # an RDF term. If a String is given, first tries to interpret it
+      # as a valid URI, then tries to append it to base_uri. Finally,
+      # raises an error if no valid term can be built.
+      # 
+      # The argument must be an RDF::Node, an object that responds to
+      # #to_uri, a String that represents a valid URI, or a String that
+      # appends to the Resource's base_uri to create a valid URI.
+      #
+      # @TODO: URI.scheme_list is naive and incomplete. Find a better 
+      #   way to check for an existing scheme.
       #
-      # @TODO: URI.scheme_list is naive and incomplete. Find a better way to check for an existing scheme.
+      # @param uri_or_str [RDF::Resource, String]
+      # 
+      # @return [RDF::Resource] A term
+      # @raise [RuntimeError] no valid RDF term could be built
       def get_uri(uri_or_str)
         return uri_or_str.to_uri if uri_or_str.respond_to? :to_uri
         return uri_or_str if uri_or_str.kind_of? RDF::Node