diff --git a/src/view-registry.coffee b/src/view-registry.coffee
index 5fbfba729..f5f8651df 100644
--- a/src/view-registry.coffee
+++ b/src/view-registry.coffee
@@ -15,6 +15,9 @@ AnyConstructor = Symbol('any-constructor')
 # application logic and is the primary point of API interaction. The view
 # just handles presentation.
 #
+# Note: Models can be any object, but must implement a `getTitle()` function
+# if they are to be displayed in a {Pane}
+#
 # View providers inform the workspace how your model objects should be
 # presented in the DOM. A view provider must always return a DOM node, which
 # makes [HTML 5 custom elements](http://www.html5rocks.com/en/tutorials/webcomponents/customelements/)
diff --git a/src/workspace.coffee b/src/workspace.coffee
index c2ed18705..bde2a62d3 100644
--- a/src/workspace.coffee
+++ b/src/workspace.coffee
@@ -589,7 +589,11 @@ class Workspace extends Model
 
   # Public: Register an opener for a uri.
   #
-  # An {TextEditor} will be used if no openers return a value.
+  # When a URI is opened via {Workspace::open}, Atom loops through its registered
+  # opener functions until one returns a value for the given uri.
+  # Openers are expected to return an object that inherits from HTMLElement or
+  # a model which has an associated view in the {ViewRegistry}.
+  # A {TextEditor} will be used if no opener returns a value.
   #
   # ## Examples
   #