diff --git a/src/panel.coffee b/src/panel.coffee
index 87284eea8..048d6840e 100644
--- a/src/panel.coffee
+++ b/src/panel.coffee
@@ -1,13 +1,25 @@
 {Emitter} = require 'event-kit'
 
-# Public:
+# Extended: A container representing a panel on the edges of the editor window.
+# You should not create a `Panel` directly, instead use {Workspace::addTopPanel}
+# and friends to add panels.
+#
+# Examples: [tree-view](https://github.com/atom/tree-view),
+# [status-bar](https://github.com/atom/status-bar),
+# and [find-and-replace](https://github.com/atom/find-and-replace) all use
+# panels.
 module.exports =
 class Panel
+  ###
+  Section: Construction and Destruction
+  ###
+
   constructor: ({@viewRegistry, @item, @visible, @priority}) ->
     @emitter = new Emitter
     @visible ?= true
     @priority ?= 100
 
+  # Public: Destroy and remove this panel from the UI.
   destroy: ->
     @emitter.emit 'did-destroy', this
 
@@ -15,34 +27,51 @@ class Panel
   Section: Event Subscription
   ###
 
+  # Public: Invoke the given callback when the pane hidden or shown.
+  #
+  # * `callback` {Function} to be called when the pane is destroyed.
+  #   * `visible` {Boolean} true when the panel has been shown
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
+  onDidChangeVisible: (callback) ->
+    @emitter.on 'did-change-visible', callback
+
   # Public: Invoke the given callback when the pane is destroyed.
   #
   # * `callback` {Function} to be called when the pane is destroyed.
+  #   * `panel` {Panel} this panel
   #
   # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidDestroy: (callback) ->
     @emitter.on 'did-destroy', callback
 
-  onDidChangeVisible: (callback) ->
-    @emitter.on 'did-change-visible', callback
-
   ###
   Section: Panel Details
   ###
 
+  # Public: Gets this panel model's view DOM node.
+  #
+  # Returns an `<atom-panel>` {Element}
   getView: -> @viewRegistry.getView(this)
 
+  # Public: Gets your panel contents view.
+  #
+  # Returns an {Element} or jQuery element, depeneding on how you created the panel.
   getItemView: -> @viewRegistry.getView(@item)
 
+  # Public: Returns a {Number} indicating this panel's priority.
   getPriority: -> @priority
 
+  # Public: Returns a {Boolean} true when the panel is visible.
   isVisible: -> @visible
 
+  # Public: Hide this panel
   hide: ->
     wasVisible = @visible
     @visible = false
     @emitter.emit 'did-change-visible', @visible if wasVisible
 
+  # Public: Show this panel
   show: ->
     wasVisible = @visible
     @visible = true