Merge pull request #1700 from atom/ks-single-apm

Remove apm from node_modules

.npmrc

@@ -0,0 +1,2 @@
+ca =
+cache = ~/.atom/.npm

docs/creating-a-package.md

@@ -338,7 +338,7 @@ code depending on whether the tests passed or failed.
 
 ## Publishing
 
-Atom bundles a command line utility called [apm] which can be used to publish
+Atom bundles a command line utility called apm which can be used to publish
 Atom packages to the public registry.
 
 Once your package is written and ready for distribution you can run the
@@ -355,3 +355,25 @@ registry.
 
 Run `apm help publish` to see all the available options and `apm help` to see
 all the other available commands.
+
+[file-tree]: https://github.com/atom/tree-view
+[status-bar]: https://github.com/atom/status-bar
+[cs-syntax]: https://github.com/atom/language-coffee-script
+[npm]: http://en.wikipedia.org/wiki/Npm_(software)
+[npm-keys]: https://npmjs.org/doc/json.html
+[git-tag]: http://git-scm.com/book/en/Git-Basics-Tagging
+[wrap-guide]: https://github.com/atom/wrap-guide/
+[keymaps]: advanced/keymaps.md
+[theme-variables]: theme-variables.md
+[tm-tokens]: http://manual.macromates.com/en/language_grammars.html
+[spacepen]: https://github.com/nathansobo/space-pen
+[path]: http://nodejs.org/docs/latest/api/path.html
+[jquery]: http://jquery.com/
+[underscore]: http://underscorejs.org/
+[jasmine]: http://jasmine.github.io
+[cson]: https://github.com/atom/season
+[less]: http://lesscss.org
+[ui-variables]: https://github.com/atom/atom-dark-ui/blob/master/stylesheets/ui-variables.less
+[first-package]: your-first-package.html
+[convert-bundle]: converting-a-text-mate-bundle.html
+[convert-theme]: converting-a-text-mate-theme.html

docs/customizing-atom.md

@@ -1,7 +1,7 @@
 # Customizing Atom
 
 To change a setting, configure a theme, or install a package just open the
-Settings view in the current window by pressing `cmd+,`.
+Settings view in the current window by pressing `cmd-,`.
 
 ## Changing The Theme
 
@@ -86,7 +86,7 @@ currently in use.
 ## Advanced Configuration
 
 Atom loads configuration settings from the `config.cson` file in your _~/.atom_
-directory, which contains CoffeeScript-style JSON:
+directory, which contains [CoffeeScript-style JSON][CSON] (CSON):
 
 ```coffee
 'core':
@@ -141,13 +141,21 @@ You can open this file in an editor from the _Atom > Open Your Config_ menu.
 ### init.coffee
 
 When Atom finishes loading, it will evaluate _init.coffee_ in your _~/.atom_
-directory, giving you a chance to run arbitrary personal CoffeeScript code to
+directory, giving you a chance to run arbitrary personal [CoffeeScript][] code to
 make customizations. You have full access to Atom's API from code in this file.
 If customizations become extensive, consider [creating a package][creating-a-package].
 
 You can open this file in an editor from the _Atom > Open Your Init Script_
 menu.
 
+For example, if you have the Audio Beep configuration setting enabled, you
+could add the following code to your _~/.atom/init.coffee_ file to have Atom
+greet you with an audio beep every time it loads:
+
+```coffee
+atom.beep()
+```
+
 This file can also be named _init.js_ and contain JavaScript code.
 
 ### styles.less
@@ -174,3 +182,5 @@ This file can also be named _styles.css_ and contain CSS.
 [creating-a-package]: creating-a-package.md
 [create-theme]: creating-a-theme.md
 [LESS]: http://www.lesscss.org
+[CSON]: https://github.com/atom/season
+[CoffeeScript]: http://coffeescript.org/

exports/atom.coffee

@@ -21,3 +21,4 @@ unless process.env.ATOM_SHELL_INTERNAL_RUN_AS_NODE
   module.exports.Task = require '../src/task'
   module.exports.View = View
   module.exports.WorkspaceView = require '../src/workspace-view'
+  module.exports.Workspace = require '../src/workspace'

menus/darwin.cson

@@ -7,6 +7,7 @@
       { label: "VERSION", enabled: false }
       { label: "Restart and Install Update", command: 'application:install-update', visible: false}
       { label: "Check for Update", command: 'application:check-for-update', visible: false}
+      { label: "Downloading Update", command: 'application:check-for-update', enabled: false, visible: false}
       { type: 'separator' }
       { label: 'Preferences...', command: 'application:show-settings' }
       { label: 'Open Your Config', command: 'application:open-your-config' }

package.json

@@ -1,7 +1,7 @@
 {
   "name": "atom",
   "productName": "Atom",
-  "version": "0.63.0",
+  "version": "0.67.0",
   "main": "./src/browser/main.js",
   "repository": {
     "type": "git",
@@ -11,7 +11,7 @@
     "url": "https://github.com/atom/atom/issues"
   },
   "license": "All Rights Reserved",
-  "atomShellVersion": "0.10.3",
+  "atomShellVersion": "0.10.4",
   "dependencies": {
     "async": "0.2.6",
     "bootstrap": "git://github.com/atom/bootstrap.git#6af81906189f1747fd6c93479e3d998ebe041372",
@@ -41,6 +41,7 @@
     "random-words": "0.0.1",
     "runas": "0.5.x",
     "scandal": "0.15.0",
+    "scrollbar-style": "^0.1.0",
     "season": ">=1.0.2 <2.0",
     "semver": "1.1.4",
     "serializable": "1.x",
@@ -52,70 +53,70 @@
     "vm-compatibility-layer": "0.1.0"
   },
   "packageDependencies": {
-    "atom-dark-syntax": "0.14.0",
+    "atom-dark-syntax": "0.15.0",
     "atom-dark-ui": "0.23.0",
-    "atom-light-syntax": "0.14.0",
+    "atom-light-syntax": "0.15.0",
     "atom-light-ui": "0.22.0",
-    "base16-tomorrow-dark-theme": "0.12.0",
-    "solarized-dark-syntax": "0.10.0",
-    "solarized-light-syntax": "0.6.0",
+    "base16-tomorrow-dark-theme": "0.13.0",
+    "solarized-dark-syntax": "0.12.0",
+    "solarized-light-syntax": "0.7.0",
     "archive-view": "0.26.0",
-    "autocomplete": "0.24.0",
+    "autocomplete": "0.26.0",
     "autoflow": "0.15.0",
     "autosave": "0.12.0",
-    "background-tips": "0.8.0",
+    "background-tips": "0.9.0",
     "bookmarks": "0.21.0",
     "bracket-matcher": "0.23.0",
-    "command-palette": "0.18.0",
+    "command-palette": "0.19.0",
     "dev-live-reload": "0.28.0",
-    "exception-reporting": "0.16.0",
-    "feedback": "0.27.0",
-    "find-and-replace": "0.87.0",
-    "fuzzy-finder": "0.38.0",
+    "exception-reporting": "0.17.0",
+    "feedback": "0.28.0",
+    "find-and-replace": "0.89.0",
+    "fuzzy-finder": "0.39.0",
     "git-diff": "0.25.0",
     "go-to-line": "0.18.0",
     "grammar-selector": "0.22.0",
-    "image-view": "0.27.0",
+    "image-view": "0.28.0",
     "keybinding-resolver": "0.11.0",
-    "link": "0.19.0",
-    "markdown-preview": "0.43.0",
+    "link": "0.20.0",
+    "markdown-preview": "0.44.0",
     "metrics": "0.30.0",
     "open-on-github": "0.23.0",
-    "package-generator": "0.29.0",
-    "release-notes": "0.25.0",
-    "settings-view": "0.85.0",
-    "snippets": "0.32.0",
+    "package-generator": "0.30.0",
+    "release-notes": "0.26.0",
+    "settings-view": "0.89.0",
+    "snippets": "0.33.0",
     "spell-check": "0.26.0",
-    "status-bar": "0.33.0",
+    "status-bar": "0.35.0",
     "styleguide": "0.26.0",
-    "symbols-view": "0.40.0",
-    "tabs": "0.24.0",
-    "timecop": "0.15.0",
-    "tree-view": "0.72.0",
-    "update-package-dependencies": "0.4.0",
+    "symbols-view": "0.41.0",
+    "tabs": "0.27.0",
+    "timecop": "0.17.0",
+    "tree-view": "0.74.0",
+    "update-package-dependencies": "0.5.0",
     "welcome": "0.11.0",
-    "whitespace": "0.15.0",
+    "whitespace": "0.16.0",
     "wrap-guide": "0.16.0",
-    "language-c": "0.12.0",
-    "language-coffee-script": "0.14.0",
-    "language-css": "0.10.0",
+    "language-c": "0.13.0",
+    "language-coffee-script": "0.15.0",
+    "language-css": "0.11.0",
     "language-gfm": "0.19.0",
     "language-git": "0.9.0",
-    "language-go": "0.6.0",
-    "language-html": "0.8.0",
+    "language-go": "0.7.0",
+    "language-html": "0.10.0",
     "language-hyperlink": "0.8.0",
     "language-java": "0.8.0",
-    "language-javascript": "0.13.0",
+    "language-javascript": "0.15.0",
     "language-json": "0.8.0",
     "language-less": "0.6.0",
     "language-make": "0.9.0",
     "language-objective-c": "0.9.0",
     "language-perl": "0.8.0",
-    "language-php": "0.8.0",
+    "language-php": "0.9.0",
     "language-property-list": "0.7.0",
-    "language-python": "0.9.0",
-    "language-ruby": "0.13.0",
-    "language-ruby-on-rails": "0.7.0",
+    "language-python": "0.11.0",
+    "language-ruby": "0.14.0",
+    "language-ruby-on-rails": "0.10.0",
     "language-sass": "0.8.0",
     "language-shellscript": "0.7.0",
     "language-source": "0.7.0",

script/bootstrap

@@ -25,21 +25,21 @@ if (!fs.existsSync(apmInstallPath))
 if (!fs.existsSync(path.join(apmInstallPath, 'node_modules')))
   fs.mkdirSync(path.join(apmInstallPath, 'node_modules'));
 
+var apmPath = 'apm/node_modules/atom-package-manager/bin/apm'
 var apmFlags = process.env.JANKY_SHA1 || process.argv.indexOf('--no-color') !== -1 ? '--no-color' : '';
 var packagesToDedupe = ['fs-plus', 'humanize-plus', 'oniguruma', 'roaster', 'season'];
+var npmCommand = 'npm --userconfig=' + path.resolve('.npmrc') + ' ';
 var echoNewLine = process.platform == 'win32' ? 'echo.' : 'echo';
 var commands = [
   'git submodule --quiet sync',
   'git submodule --quiet update --recursive --init',
-  {command: 'npm --strict-ssl=false install --quiet', options: {cwd: path.resolve(__dirname, '..', 'build'), ignoreStdout: true}},
-  {command: 'npm --strict-ssl=false install --quiet', options: {cwd: apmVendorPath, ignoreStdout: true}},
-  {command: 'npm --strict-ssl=false install --quiet ' + apmVendorPath, options: {cwd: apmInstallPath, ignoreStdout: true}},
-  {command: 'npm --strict-ssl=false install --quiet ' + apmVendorPath, options: {ignoreStdout: true}},
-  {command: 'node ../../apm/node_modules/atom-package-manager/bin/apm rebuild', options: {cwd: path.resolve('node_modules', 'atom-package-manager'), ignoreStdout: true}},
+  {command: npmCommand + 'install --quiet', options: {cwd: path.resolve(__dirname, '..', 'build'), ignoreStdout: true}},
+  {command: npmCommand + 'install --quiet', options: {cwd: apmVendorPath, ignoreStdout: true}},
+  {command: npmCommand + 'install --quiet ' + apmVendorPath, options: {cwd: apmInstallPath, ignoreStdout: true}},
   echoNewLine,
-  'node apm/node_modules/atom-package-manager/bin/apm clean ' + apmFlags,
-  'node apm/node_modules/atom-package-manager/bin/apm install --quiet ' + apmFlags,
-  'node apm/node_modules/atom-package-manager/bin/apm dedupe --quiet ' + apmFlags + ' ' + packagesToDedupe.join(' '),
+  apmPath + ' clean ' + apmFlags,
+  apmPath + ' install --quiet ' + apmFlags,
+  apmPath + ' dedupe --quiet ' + apmFlags + ' ' + packagesToDedupe.join(' '),
 ];
 
 process.chdir(path.dirname(__dirname));

script/clean

@@ -22,6 +22,7 @@ var commands = [
   [__dirname, '..', 'atom-shell'],
   [home, '.atom', '.node-gyp'],
   [home, '.atom', 'storage'],
+  [home, '.atom', '.npm'],
   [tmpdir, 'atom-build'],
   [tmpdir, 'atom-cached-atom-shells'],
   [tmpdir, 'atom-compile-cache'],

spec/display-buffer-spec.coffee

@@ -600,6 +600,13 @@ describe "DisplayBuffer", ->
       expect(displayBuffer.screenPositionForBufferPosition([0, 1])).toEqual [0, 2]
       expect(displayBuffer.bufferPositionForScreenPosition([0, 2])).toEqual [0, 1]
 
+    it "correctly translates positions on soft wrapped lines containing tabs", ->
+      buffer.setText('\t\taa  bb  cc  dd  ee  ff  gg')
+      displayBuffer.setSoftWrap(true)
+      displayBuffer.setEditorWidthInChars(10)
+      expect(displayBuffer.screenPositionForBufferPosition([0, 10], wrapAtSoftNewlines: true)).toEqual [1, 0]
+      expect(displayBuffer.bufferPositionForScreenPosition([1, 0])).toEqual [0, 10]
+
   describe ".getMaxLineLength()", ->
     it "returns the length of the longest screen line", ->
       expect(displayBuffer.getMaxLineLength()).toBe 65

spec/editor-view-spec.coffee

@@ -1806,6 +1806,17 @@ describe "EditorView", ->
         runs ->
           expect(editor.getSoftWrapColumn()).toBeLessThan previousSoftWrapColumn
 
+      it "accounts for the width of the scrollbar if there is one", ->
+        # force the scrollbar to always be visible, regardless of OS visibility setting
+        $('#jasmine-content').prepend """
+          <style>
+            ::-webkit-scrollbar { width: 15px; }
+          </style>
+        """
+        setEditorHeightInLines(editorView, 5)
+        setEditorWidthInChars(editorView, 40)
+        expect(editor.lineForScreenRow(2).text.length).toBe 34
+
   describe "gutter rendering", ->
     beforeEach ->
       editorView.attachToDom(heightInLines: 5.5)

spec/workspace-view-spec.coffee

@@ -241,3 +241,11 @@ describe "WorkspaceView", ->
       expect(atom.workspaceView.getActivePane().getItems()).toHaveLength 1
       atom.workspaceView.trigger('core:close')
       expect(atom.workspaceView.getActivePane().getItems()).toHaveLength 0
+
+  describe "the scrollbar visibility class", ->
+    it "has a class based on the style of the scrollbar", ->
+      scrollbarStyle = require 'scrollbar-style'
+      scrollbarStyle.emitValue 'legacy'
+      expect(atom.workspaceView).toHaveClass 'scrollbars-visible-always'
+      scrollbarStyle.emitValue 'overlay'
+      expect(atom.workspaceView).toHaveClass 'scrollbars-visible-when-scrolling'

src/browser/application-menu.coffee

@@ -71,11 +71,28 @@ class ApplicationMenu
 
   # Toggles Install Update Item
   showInstallUpdateItem: (visible=true) ->
+    if visible
+      @showDownloadingUpdateItem(false)
+      @showCheckForUpdateItem(false)
+
     if (item = _.find(@flattenMenuItems(@menu), (i) -> i.label == 'Restart and Install Update'))
       item.visible = visible
 
+  # Toggles Downloading Update Item
+  showDownloadingUpdateItem: (visible=true) ->
+    if visible
+      @showInstallUpdateItem(false)
+      @showCheckForUpdateItem(false)
+
+    if (item = _.find(@flattenMenuItems(@menu), (i) -> i.label == 'Downloading Update'))
+      item.visible = visible
+
   # Toggles Check For Update Item
   showCheckForUpdateItem: (visible=true) ->
+    if visible
+      @showDownloadingUpdateItem(false)
+      @showInstallUpdateItem(false)
+
     if (item = _.find(@flattenMenuItems(@menu), (i) -> i.label == 'Check for Update'))
       item.visible = visible
 

src/browser/atom-application.coffee

@@ -133,48 +133,38 @@ class AtomApplication
     autoUpdater.setFeedUrl "https://atom.io/api/updates?version=#{@version}"
 
     autoUpdater.on 'checking-for-update', =>
+      @applicationMenu.showDownloadingUpdateItem(false)
       @applicationMenu.showInstallUpdateItem(false)
       @applicationMenu.showCheckForUpdateItem(false)
 
     autoUpdater.on 'update-not-available', =>
-      @applicationMenu.showInstallUpdateItem(false)
       @applicationMenu.showCheckForUpdateItem(true)
 
+    autoUpdater.on 'update-available', =>
+      @applicationMenu.showDownloadingUpdateItem(true)
+
     autoUpdater.on 'update-downloaded', (event, releaseNotes, releaseName, releaseDate, releaseURL) =>
       atomWindow.sendCommand('window:update-available', [releaseName, releaseNotes]) for atomWindow in @windows
       @applicationMenu.showInstallUpdateItem(true)
-      @applicationMenu.showCheckForUpdateItem(false)
       @updateVersion = releaseName
 
     autoUpdater.on 'error', (event, message) =>
-      @applicationMenu.showInstallUpdateItem(false)
       @applicationMenu.showCheckForUpdateItem(true)
 
     # Check for update after Atom has fully started and the menus are created
     setTimeout((-> autoUpdater.checkForUpdates()), 5000)
 
   checkForUpdate: ->
-    autoUpdater.once 'update-available', ->
-      dialog.showMessageBox
-        type: 'info'
-        buttons: ['OK']
-        message: 'Update available.'
-        detail: 'A new update is being downloaded.'
+    @onUpdateNotAvailable ?= =>
+      autoUpdater.removeListener 'error', @onUpdateError
+      dialog.showMessageBox type: 'info', buttons: ['OK'], message: 'No update available.', detail: "Version #{@version} is the latest version."
 
-    autoUpdater.once 'update-not-available', =>
-      dialog.showMessageBox
-        type: 'info'
-        buttons: ['OK']
-        message: 'No update available.'
-        detail: "Version #{@version} is the latest version."
-
-    autoUpdater.once 'error', (event, message)->
-      dialog.showMessageBox
-        type: 'warning'
-        buttons: ['OK']
-        message: 'There was an error checking for updates.'
-        detail: message
+    @onUpdateError ?= (event, message) =>
+      autoUpdater.removeListener 'update-not-available', @onUpdateNotAvailable
+      dialog.showMessageBox type: 'warning', buttons: ['OK'], message: 'There was an error checking for updates.', detail: message
 
+    autoUpdater.on 'update-not-available', @onUpdateNotAvailable
+    autoUpdater.on 'error', @onUpdateError
     autoUpdater.checkForUpdates()
 
   # Registers basic application commands, non-idempotent.

src/browser/atom-window.coffee

@@ -104,7 +104,7 @@ class AtomWindow
         type: 'warning'
         buttons: ['Close Window', 'Reload', 'Keep It Open']
         message: 'The editor has crashed'
-        detail: 'Please report this issue to https://github.com/atom/atom/issues'
+        detail: 'Please report this issue to atom@github.com'
       switch chosen
         when 0 then @browserWindow.destroy()
         when 1 then @browserWindow.restart()

src/editor-view.coffee

@@ -667,11 +667,15 @@ class EditorView extends View
     @editor.setSoftWrap(not @editor.getSoftWrap())
 
   calculateWidthInChars: ->
-    Math.floor(@scrollView.width() / @charWidth)
+    Math.floor((@scrollView.width() - @getScrollbarWidth()) / @charWidth)
 
   calculateHeightInLines: ->
     Math.ceil($(window).height() / @lineHeight)
 
+  getScrollbarWidth: ->
+    scrollbarElement = @verticalScrollbar[0]
+    scrollbarElement.offsetWidth - scrollbarElement.clientWidth
+
   # Public: Enables/disables soft wrap on the editor.
   #
   # softWrap - A {Boolean} which, if `true`, enables soft wrap

src/editor.coffee

@@ -1733,3 +1733,7 @@ class Editor extends Model
 
   getSelectionMarkerAttributes: ->
     type: 'selection', editorId: @id, invalidate: 'never'
+
+  # Deprecated: Call {::joinLines} instead.
+  joinLine: ->
+    @joinLines()

src/package-manager.coffee

@@ -41,7 +41,7 @@ class PackageManager
 
   # Public: Get the path to the apm command
   getApmPath: ->
-    @apmPath ?= require.resolve('atom-package-manager/bin/apm')
+    @apmPath ?= path.resolve(__dirname, '..', 'apm', 'node_modules', 'atom-package-manager', 'bin', 'apm')
 
   # Public: Get the paths being used to look for packages.
   #

src/select-list-view.coffee

@@ -56,6 +56,11 @@ class SelectListView extends View
     @filterEditorView.hiddenInput.on 'focusout', =>
       @cancel() unless @cancelling
 
+    # This prevents the focusout event from firing on the filter editor view
+    # when the list is scrolled by clicking the scrollbar and dragging.
+    @list.on 'mousedown', ({target}) =>
+      false if target is @list[0]
+
     @on 'core:move-up', =>
       @selectPreviousItemView()
     @on 'core:move-down', =>

src/tokenized-line.coffee

@@ -6,6 +6,7 @@ class TokenizedLine
     @tokens = @breakOutAtomicTokens(tokens, tabLength)
     @startBufferColumn ?= 0
     @text = _.pluck(@tokens, 'value').join('')
+    @bufferDelta = _.sum(_.pluck(@tokens, 'bufferDelta'))
 
   copy: ->
     new TokenizedLine({@tokens, @lineEnding, @ruleStack, @startBufferColumn, @fold})
@@ -55,7 +56,7 @@ class TokenizedLine
       @text.length
 
   getMaxBufferColumn: ->
-    @startBufferColumn + @getMaxScreenColumn()
+    @startBufferColumn + @bufferDelta
 
   softWrapAt: (column) ->
     return [new TokenizedLine([], '', [0, 0], [0, 0]), this] if column == 0
@@ -78,7 +79,7 @@ class TokenizedLine
     )
     rightFragment = new TokenizedLine(
       tokens: rightTokens
-      startBufferColumn: @startBufferColumn + column
+      startBufferColumn: @bufferColumnForScreenColumn(column)
       ruleStack: @ruleStack
       lineEnding: @lineEnding
     )

src/workspace-view.coffee

@@ -3,6 +3,7 @@ path = require 'path'
 Q = require 'q'
 _ = require 'underscore-plus'
 Delegator = require 'delegato'
+scrollbarStyle = require 'scrollbar-style'
 {$, $$, View} = require './space-pen-extensions'
 fs = require 'fs-plus'
 Workspace = require './workspace'
@@ -14,38 +15,42 @@ PaneRowView = require './pane-row-view'
 PaneContainerView = require './pane-container-view'
 Editor = require './editor'
 
-# Public: The container for the entire Atom application.
+# Public: The top-level view for the entire window. An instance of this class is
+# available via the `atom.workspaceView` global.
 #
-# An instance of this class is always available as the `atom.workspaceView`
-# global.
+# It is backed by a model object, an instance of {Workspace}, which is available
+# via the `atom.workspace` global or {::getModel}. You should prefer to interact
+# with the model object when possible, but it won't always be possible with the
+# current API.
 #
-# ## Commands
+# ## Adding Perimiter Panels
 #
-#  * `application:about` - Opens the about dialog.
-#  * `application:show-settings` - Opens the preference pane in the currently
-#    focused editor.
-#  * `application:quit` - Quits the entire application.
-#  * `application:hide` - Hides the entire application.
-#  * `application:hide-other-applications` - Hides other applications
-#    running on the system.
-#  * `application:unhide-other-applications` - Shows other applications
-#    that were previously hidden.
-#  * `application:new-window` - Opens a new {AtomWindow} with no {Project}
-#    path.
-#  * `application:new-file` - Creates a new file within the focused window.
-#    Note: only one new file may exist within an {AtomWindow} at a time.
-#  * `application:open` - Prompts the user for a path to open in a new {AtomWindow}
-#  * `application:minimize` - Minimizes the currently focused {AtomWindow}
-#  * `application:zoom` - Expands the window to fill the screen or returns it to
-#    it's original unzoomed size.
-#  * `application:bring-all-windows-to-front` - Brings all {AtomWindow}s to the
-#    the front.
+# Use the following methods if possible to attach panels to the perimiter of the
+# workspace rather than manipulating the DOM directly to better insulate you to
+# changes in the workspace markup:
+#
+# * {::prependToTop}
+# * {::appendToTop}
+# * {::prependToBottom}
+# * {::appendToBottom}
+# * {::prependToLeft}
+# * {::appendToLeft}
+# * {::prependToRight}
+# * {::appendToRigt}
 #
 # ## Requiring in package specs
 #
+# If you need a `WorkspaceView` instance to test your package, require it via
+# the built-in `atom` module.
+#
 # ```coffee
 #   {WorkspaceView} = require 'atom'
 # ```
+#
+# You can assign it to the `atom.workspaceView` global in the spec or just use
+# it as a local, depending on what you're trying to accomplish. Building the
+# `WorkspaceView` is currently expensive, so you should try build a {Workspace}
+# instead if possible.
 module.exports =
 class WorkspaceView extends View
   Delegator.includeInto(this)
@@ -81,6 +86,14 @@ class WorkspaceView extends View
 
     @subscribe @model, 'uri-opened', => @trigger 'uri-opened'
 
+    @subscribe scrollbarStyle, (style) =>
+      @removeClass('scrollbars-visible-always scrollbars-visible-when-scrolling')
+      switch style
+        when 'legacy'
+          @addClass("scrollbars-visible-always")
+        when 'overlay'
+          @addClass("scrollbars-visible-when-scrolling")
+
     @updateTitle()
 
     @on 'focus', (e) => @handleFocus(e)
@@ -139,6 +152,12 @@ class WorkspaceView extends View
     @command 'core:save', => @saveActivePaneItem()
     @command 'core:save-as', => @saveActivePaneItemAs()
 
+  # Public: Get the underlying model object.
+  #
+  # Returns a {Workspace}.
+  getModel: -> @model
+
+  # Public: Install the Atom shell commands on the user's system.
   installShellCommands: ->
     showErrorDialog = (error) ->
       installDirectory = CommandInstaller.getInstallDirectory()
@@ -176,11 +195,11 @@ class WorkspaceView extends View
   afterAttach: (onDom) ->
     @focus() if onDom
 
-  # Public: Shows a dialog asking if the pane was _really_ meant to be closed.
+  # Prompts to save all unsaved items
   confirmClose: ->
     @panes.confirmClose()
 
-  # Public: Updates the application's title, based on whichever file is open.
+  # Updates the application's title, based on whichever file is open.
   updateTitle: ->
     if projectPath = atom.project.getPath()
       if item = @getActivePaneItem()
@@ -190,85 +209,119 @@ class WorkspaceView extends View
     else
       @setTitle('untitled')
 
-  # Public: Sets the application's title.
+  # Sets the application's title.
   setTitle: (title) ->
     document.title = title
 
-  # Returns an Array of  all of the application's {EditorView}s.
+  # Get all editor views.
+  #
+  # You should prefer {Workspace::getEditors} unless you absolutely need access
+  # to the view objects. Also consider using {::eachEditorView}, which will call
+  # a callback for all current and *future* editor views.
+  #
+  # Returns an {Array} of {EditorView}s.
   getEditorViews: ->
     @panes.find('.pane > .item-views > .editor').map(-> $(this).view()).toArray()
 
-  # Public: Prepends the element to the top of the window.
+  # Public: Prepend an element or view to the panels at the top of the
+  # workspace.
   prependToTop: (element) ->
     @vertical.prepend(element)
 
-  # Public: Appends the element to the top of the window.
+  # Public: Append an element or view to the panels at the top of the workspace.
   appendToTop: (element) ->
     @panes.before(element)
 
-  # Public: Prepends the element to the bottom of the window.
+  # Public: Prepend an element or view to the panels at the bottom of the
+  # workspace.
   prependToBottom: (element) ->
     @panes.after(element)
 
-  # Public: Appends the element to bottom of the window.
+  # Public: Append an element or view to the panels at the bottom of the
+  # workspace.
   appendToBottom: (element) ->
     @vertical.append(element)
 
-  # Public: Prepends the element to the left side of the window.
+  # Public: Prepend an element or view to the panels at the left of the
+  # workspace.
   prependToLeft: (element) ->
     @horizontal.prepend(element)
 
-  # Public: Appends the element to the left side of the window.
+  # Public: Append an element or view to the panels at the left of the
+  # workspace.
   appendToLeft: (element) ->
     @vertical.before(element)
 
-  # Public: Prepends the element to the right side of the window.
+  # Public: Prepend an element or view to the panels at the right of the
+  # workspace.
   prependToRight: (element) ->
     @vertical.after(element)
 
-  # Public: Appends the element to the right side of the window.
+  # Public: Append an element or view to the panels at the right of the
+  # workspace.
   appendToRight: (element) ->
     @horizontal.append(element)
 
-  # Public: Returns the currently focused {PaneView}.
+  # Public: Get the active pane view.
+  #
+  # Prefer {Workspace::getActivePane} if you don't actually need access to the
+  # view.
+  #
+  # Returns a {PaneView}.
   getActivePaneView: ->
     @panes.getActivePane()
 
-  # Public: Returns the currently focused item from within the focused {PaneView}
-  getActivePaneItem: ->
-    @model.activePaneItem
-
-  # Public: Returns the view of the currently focused item.
+  # Public: Get the view associated with the active pane item.
+  #
+  # Returns a view.
   getActiveView: ->
     @panes.getActiveView()
 
-  # Public: Focuses the previous pane by id.
+  # Focus the previous pane by id.
   focusPreviousPaneView: -> @model.activatePreviousPane()
 
-  # Public: Focuses the next pane by id.
+  # Focus the next pane by id.
   focusNextPaneView: -> @model.activateNextPane()
 
-  # Public: Focuses the pane directly above the active pane.
+  # Public: Focus the pane directly above the active pane.
   focusPaneViewAbove: -> @panes.focusPaneViewAbove()
 
-  # Public: Focuses the pane directly below the active pane.
+  # Public: Focus the pane directly below the active pane.
   focusPaneViewBelow: -> @panes.focusPaneViewBelow()
 
-  # Public: Focuses the pane directly to the left of the active pane.
+  # Public: Focus the pane directly to the left of the active pane.
   focusPaneViewOnLeft: -> @panes.focusPaneViewOnLeft()
 
-  # Public: Focuses the pane directly to the right of the active pane.
+  # Public: Focus the pane directly to the right of the active pane.
   focusPaneViewOnRight: -> @panes.focusPaneViewOnRight()
 
-  # Public: Fires a callback on each open {PaneView}.
+  # Public: Register a function to be called for every current and future
+  # pane view in the workspace.
+  #
+  # callback - A {Function} with a {PaneView} as its only argument.
+  #
+  # Returns a subscription object with an `.off` method that you can call to
+  # unregister the callback.
   eachPaneView: (callback) ->
     @panes.eachPaneView(callback)
 
+  # Public: Get all existing pane views.
+  #
+  # Prefer {Workspace::getPanes} if you don't need access to the view objects.
+  # Also consider using {::eachPaneView} or {Workspace::eachPane} if you want
+  # to register a callback for all current and *future* pane views or panes.
+  #
   # Returns an Array of all open {PaneView}s.
   getPaneViews: ->
     @panes.getPanes()
 
-  # Public: Fires a callback on each open {EditorView}.
+  # Public: Register a function to be called for every current and future
+  # editor view in the workspace.
+  #
+  # callback - A {Function} with an {EditorView} as its only argument.
+  #
+  # Returns a subscription object with an `.off` method that you can call to
+  # unregister the callback.
   eachEditorView: (callback) ->
     callback(editor) for editor in @getEditorViews()
     attachedCallback = (e, editor) -> callback(editor)
@@ -290,3 +343,7 @@ class WorkspaceView extends View
   # Deprecated
   getActivePane: ->
     @getActivePaneView()
+
+  # Deprecated: Call {Workspace::getActivePaneItem} instead.
+  getActivePaneItem: ->
+    @model.activePaneItem

src/workspace.coffee

@@ -7,10 +7,12 @@ Delegator = require 'delegato'
 PaneContainer = require './pane-container'
 Pane = require './pane'
 
-# Public: Represents the view state of the entire window, including the panes at
-# the center and panels around the periphery.
+# Public: Represents the state of the user interface for the entire window.
+# An instance of this class is available via the `atom.workspace` global.
 #
-# An instance of this class is always available as the `atom.workspace` global.
+# Interact with this object to open files, be notified of current and future
+# editors, and manipulate panes. To add panels, you'll need to use the
+# {WorkspaceView} class for now until we establish APIs at the model layer.
 module.exports =
 class Workspace extends Model
   atom.deserializers.add(this)
@@ -49,28 +51,38 @@ class Workspace extends Model
     paneContainer: @paneContainer.serialize()
     fullScreen: atom.isFullScreen()
 
-  # Public: Calls callback for every existing {Editor} and for all new {Editor}s.
-  # that are created.
+  # Public: Register a function to be called for every current and future
+  # {Editor} in the workspace.
   #
-  # callback - A {Function} with an {Editor} as its only argument
+  # callback - A {Function} with an {Editor} as its only argument.
+  #
+  # Returns a subscription object with an `.off` method that you can call to
+  # unregister the callback.
   eachEditor: (callback) ->
     atom.project.eachEditor(callback)
 
-  # Public: Returns an {Array} of all open {Editor}s.
+  # Public: Get all current editors in the workspace.
+  #
+  # Returns an {Array} of {Editor}s.
   getEditors: ->
     atom.project.getEditors()
 
-  # Public: Asynchronously opens a given a filepath in Atom.
+  # Public: Open a given a URI in Atom asynchronously.
   #
-  # uri - A {String} uri.
-  # options  - An options {Object} (default: {}).
-  #   :initialLine - A {Number} indicating which line number to open to.
-  #   :split - A {String} ('left' or 'right') that opens the filePath in a new
-  #            pane or an existing one if it exists.
-  #   :changeFocus - A {Boolean} that allows the filePath to be opened without
-  #                  changing focus.
-  #   :searchAllPanes - A {Boolean} that will open existing editors from any pane
-  #                     if the uri is already open (default: false)
+  # uri - A {String} containing a URI.
+  # options  - An optional options {Object}
+  #   :initialLine - A {Number} indicating which row to move the cursor to
+  #                  initially. Defaults to `0`.
+  #   :split - Either 'left' or 'right'. If 'left', the item will be opened in
+  #            leftmost pane of the current active pane's row. If 'right', the
+  #            item will be opened in the rightmost pane of the current active
+  #            pane's row.
+  #   :activatePane - A {Boolean} indicating whether to call {Pane::activate} on
+  #                   the containing pane. Defaults to `true`.
+  #   :searchAllPanes - A {Boolean}. If `true`, the workspace will attempt to
+  #                     activate an existing item for the given URI on any pane.
+  #                     If `false`, only the active pane will be searched for
+  #                     an existing item for the same URI. Defaults to `false`.
   #
   # Returns a promise that resolves to the {Editor} for the file URI.
   open: (uri, options={}) ->
@@ -89,10 +101,20 @@ class Workspace extends Model
 
     @openUriInPane(uri, pane, options)
 
+  # Public: Open Atom's license in the active pane.
   openLicense: ->
     @open(join(atom.getLoadSettings().resourcePath, 'LICENSE'))
 
-  # Only used in specs
+  # Synchronously open the given URI in the active pane. **Only use this method
+  # in specs. Calling this in production code will block the UI thread and
+  # everyone will be mad at you.**
+  #
+  # uri - A {String} containing a URI.
+  # options  - An optional options {Object}
+  #   :initialLine - A {Number} indicating which row to move the cursor to
+  #                  initially. Defaults to `0`.
+  #   :activatePane - A {Boolean} indicating whether to call {Pane::activate} on
+  #                   the containing pane. Defaults to `true`.
   openSync: (uri='', options={}) ->
     {initialLine} = options
     # TODO: Remove deprecated changeFocus option
@@ -130,7 +152,8 @@ class Workspace extends Model
       .catch (error) ->
         console.error(error.stack ? error)
 
-  # Public: Reopens the last-closed item uri if it hasn't already been reopened.
+  # Public: Reopen the last-closed item's URI if it hasn't already been
+  # reopened.
   reopenItemSync: ->
     if uri = @destroyedItemUris.pop()
       @openSync(uri)
@@ -150,50 +173,70 @@ class Workspace extends Model
   registerOpener: (opener) ->
     atom.project.registerOpener(opener)
 
-  # Public: Remove a registered opener.
+  # Public: Unregister an opener registered with {::registerOpener}.
   unregisterOpener: (opener) ->
     atom.project.unregisterOpener(opener)
 
   getOpeners: ->
     atom.project.openers
 
-  # Public: Returns the active {Pane}.
+  # Public: Get the active {Pane}.
+  #
+  # Returns a {Pane}.
   getActivePane: ->
     @paneContainer.activePane
 
-  # Public: Returns the first pane {Pane} with an item for the given uri or
-  # undefined if none exists.
+  # Public: Get the first pane {Pane} with an item for the given URI.
+  #
+  # Returns a {Pane} or `undefined` if no pane exists for the given URI.
   paneForUri: (uri) ->
     @paneContainer.paneForUri(uri)
 
-  # Public: save the active item.
+  # Public: Save the active pane item.
+  #
+  # If the active pane item currently has a URI according to the item's
+  # `.getUri` method, calls `.save` on the item. Otherwise {::saveActiveItemAs}
+  # will be called instead. This method does nothing if the active item does not
+  # implement a `.save` method.
   saveActivePaneItem: ->
     @activePane?.saveActiveItem()
 
-  # Public: save the active item as.
+  # Public: Prompt the user for a path and save the active pane item to it.
+  #
+  # Opens a native dialog where the user selects a path on disk, then calls
+  # `.saveAs` on the item with the selected path. This method does nothing if
+  # the active item does not implement a `.saveAs` method.
   saveActivePaneItemAs: ->
     @activePane?.saveActiveItemAs()
 
-  # Public: destroy/close the active item.
+  # Public: Destroy (close) the active pane item.
+  #
+  # Removes the active pane item and calls the `.destroy` method on it if one is
+  # defined.
   destroyActivePaneItem: ->
     @activePane?.destroyActiveItem()
 
-  # Public: destroy/close the active pane.
+  # Public: Destroy (close) the active pane.
   destroyActivePane: ->
     @activePane?.destroy()
 
-  # Public: Returns an {Editor} if the active pane item is an {Editor},
-  # or null otherwise.
+  # Public: Get the active item if it is an {Editor}.
+  #
+  # Returns an {Editor} or `undefined` if the current active item is not an
+  # {Editor}.
   getActiveEditor: ->
     @activePane?.getActiveEditor()
 
+  # Public: Increase the editor font size by 1px.
   increaseFontSize: ->
     atom.config.set("editor.fontSize", atom.config.get("editor.fontSize") + 1)
 
+  # Public: Decrease the editor font size by 1px.
   decreaseFontSize: ->
     fontSize = atom.config.get("editor.fontSize")
     atom.config.set("editor.fontSize", fontSize - 1) if fontSize > 1
 
+  # Public: Restore to a default editor font size.
   resetFontSize: ->
     atom.config.restoreDefault("editor.fontSize")
 

static/variables/syntax-variables.less

@@ -1,8 +1,29 @@
-// This file has fallback variables. It specifies the syntax variables that
-// themes must implement.
+// This file has fallback variables. It specifies all syntax variables that
+// themes must implement if they include a syntax-variables.less file.
 
-// Colors
+// General colors
+@syntax-text-color: #333;
+@syntax-cursor-color: #333;
+@syntax-selection-color: #69c;
+@syntax-background-color: #fff;
 
-@syntax-color-added: #5293d8;
-@syntax-color-modified: #f78a46;
-@syntax-color-removed: #c00;
+// Guide colors
+@syntax-wrap-guide-color: #ccc;
+@syntax-indent-guide-color: #ccc;
+@syntax-invisible-character-color: #ccc;
+
+// For find and replace markers
+@syntax-result-marker-color: #444;
+@syntax-result-marker-color-selected: #000;
+
+// Gutter colors
+@syntax-gutter-text-color: #333;
+@syntax-gutter-text-color-selected: #000;
+@syntax-gutter-background-color: #ccc;
+@syntax-gutter-background-color-selected: #eee;
+
+// For git diff info. i.e. in the gutter
+@syntax-color-added: green;
+@syntax-color-modified: orange;
+@syntax-color-removed: red;
+@syntax-color-renamed: blue;