diff --git a/docs/advanced/scopes-and-scope-descriptors.md b/docs/advanced/scopes-and-scope-descriptors.md
index 9cf12bed9..eb5803a8a 100644
--- a/docs/advanced/scopes-and-scope-descriptors.md
+++ b/docs/advanced/scopes-and-scope-descriptors.md
@@ -42,7 +42,9 @@ atom.config.set('.source.js .function.name', 'my-package.my-setting', 'special v
 
 ## Scope Descriptors
 
-A scope descriptor is an `Array` of `String`s describing a path from the root of the syntax tree to a token including _all_ scope names for the entire path.
+A scope descriptor is an [Object][scope-descriptor] that wraps an `Array` of
+`String`s. The Array describes a path from the root of the syntax tree to a
+token including _all_ scope names for the entire path.
 
 In our JavaScript example above, a scope descriptor for the function name token would be:
 
@@ -82,3 +84,4 @@ valueForLanguage = atom.config.get(editor.getRootScopeDescriptor(), 'my-package.
 [editor-scopeDescriptorForBufferPosition]:https://atom.io/docs/api/latest/TextEditor#instance-scopeDescriptorForBufferPosition
 
 [cursor-getScopeDescriptor]:https://atom.io/docs/api/latest/Cursor#instance-getScopeDescriptor
+[scope-desctiptor]:https://atom.io/docs/api/latest/ScopeDescriptor
diff --git a/src/scope-descriptor.coffee b/src/scope-descriptor.coffee
index 55cbb9216..70dc6598d 100644
--- a/src/scope-descriptor.coffee
+++ b/src/scope-descriptor.coffee
@@ -1,5 +1,19 @@
-
-# Extended:
+# Extended: Wraps an {Array} of `String`s. The Array describes a path from the
+# root of the syntax tree to a token including _all_ scope names for the entire
+# path.
+#
+# You can use `ScopeDescriptor`s to get language-specific config settings via
+# {Config::get}.
+#
+# You should not need to create a `ScopeDescriptor` directly.
+#
+# * {Editor::getRootScopeDescriptor} to get the language's descriptor.
+# * {Editor::scopeDescriptorForBufferPosition} to get the descriptor at a
+#   specific position in the buffer.
+# * {Cursor::getScopeDescriptor} to get a cursor's descriptor based on position.
+#
+# See the [scopes and scope descriptor guide](https://atom.io/docs/v0.138.0/advanced/scopes-and-scope-descriptors)
+# for more information.
 module.exports =
 class ScopeDescriptor
   @create: (descriptor) ->
@@ -12,7 +26,10 @@ class ScopeDescriptor
   Section: Construction and Destruction
   ###
 
-  # Public:
+  # Public: Create a {ScopeDescriptor} object.
+  #
+  # * `object` {Object}
+  #   * `descriptor` {Array} of {String}s
   constructor: ({@descriptor}) ->
 
   getScopeChain: ->