     bottom: Math.max(0, fixedBottomTops...)
 
   ###*
+  Scroll's the given element's viewport so the element
+  is visible for the user.
+
+  By default Up.js will always reveal an element before
+  updating it with Javascript functions like [`up.replace`](/up.flow#up.replace)
+  or UJS behavior like [`[up-target]`](/up.link#up-target).
+
+  \#\#\#\# How Up.js finds the viewport
+
+  The viewport (the container that is going to be scrolled)
+  is the closest parent of the element that is either:
+
+  - the currently open [modal](/up.modal)
+  - an element with the attribute `[up-viewport]`
+  - the `<body>` element
+  - an element matching the selector you have configured using `up.viewport.defaults({ viewSelector: 'my-custom-selector' })`
+
+  \#\#\#\# Fixed elements obstruction the viewport
+
+  Many applications have a navigation bar fixed to the top or bottom,
+  obstructing the view on an element.
+
+  To make `up.aware` of these fixed elements you can either:
+
+  - give the element an attribute [`up-fixed="top"`](#up-fixed-top) or [`up-fixed="bottom"`](up-fixed-bottom)
+  - [configure default options](#up.layout.defaults) for `fixedTop` or `fixedBottom`
+
   @method up.reveal
   @param {String|Element|jQuery} element
   @param {String|Element|jQuery} [options.viewport]
   @param {Number} [options.duration]
   @param {String} [options.easing]
   @return {Deferred}
-  @protected
+    A promise that will be resolved when the element is revealed.
   ###
   reveal = (elementOrSelector, options) ->
-
     options = u.options(options)
-
     $element = $(elementOrSelector)
     $viewport = findViewport($element, options.viewport)
+
     viewportIsBody = $viewport.is('body')
-
     viewportHeight = if viewportIsBody then u.clientSize().height else $viewport.height()
-
     originalScrollPos = $viewport.scrollTop()
     newScrollPos = originalScrollPos
 

  SCROLL_PROMISE_KEY = 'up-scroll-promise'

  ###*
  @method up.scroll
  @param {String|Element|jQuery} viewOrSelector
  @param {Number} scrollPos
  @param {String}[options.duration]
  @param {String}[options.easing]
  @return {Deferred}
  @protected 
  ###
  scroll = (viewOrSelector, scrollTop, options) ->
    $view = $(viewOrSelector)
    options = u.options(options)
    duration = u.option(options.duration, config.duration)
    easing = u.option(options.easing, config.easing)


  ###*
  @private
  @method up.viewport.findViewport
  ###
  findViewport = ($element, viewportSelectorOrElement) ->
    $viewport = undefined
