Cleanup docs

.gitignore

@@ -9,5 +9,6 @@ debug.log
 /tags
 /atom-shell/
 docs/output
+docs/includes
 spec/fixtures/evil-files/
 /apm

build/package.json

@@ -6,9 +6,11 @@
     "url": "https://github.com/atom/atom.git"
   },
   "dependencies": {
+    "async": "~0.2.9",
     "biscotto": "0.0.17",
     "first-mate": "~0.13.0",
     "formidable": "~1.0.14",
+    "fs-plus": "1.x",
     "github-releases": "~0.2.0",
     "grunt": "~0.4.1",
     "grunt-cli": "~0.1.9",

build/tasks/docs-task.coffee

@@ -1,5 +1,8 @@
 path = require 'path'
-fs = require 'fs'
+
+async = require 'async'
+fs = require 'fs-plus'
+request = require 'request'
 
 module.exports = (grunt) ->
   cmd = path.join('node_modules', '.bin', 'coffee')
@@ -9,8 +12,36 @@ module.exports = (grunt) ->
 
   grunt.registerTask 'build-docs', 'Builds the API docs in src/app', ->
     done = @async()
-    args = [commonArgs..., '--title', 'Atom API Documentation', '-o', 'docs/output/api', 'src/', '../text-buffer/src/range.coffee', '../text-buffer/src/point.coffee', '../text-buffer/src/marker.coffee']
-    grunt.util.spawn({cmd, args, opts}, done)
+
+    downloadFileFromRepo = ({repo, file}, callback) ->
+      uri = "https://raw2.github.com/atom/#{repo}/master/#{file}"
+      request uri, (error, response, contents) ->
+        return callback(error) if error?
+        downloadPath = path.join('docs', 'includes', repo, file)
+        fs.writeFile downloadPath, contents, (error) ->
+          callback(error, downloadPath)
+
+    includes = [
+      {repo: 'space-pen',   file: 'src/space-pen.coffee'}
+      {repo: 'text-buffer', file: 'src/marker.coffee'}
+      {repo: 'text-buffer', file: 'src/point.coffee'}
+      {repo: 'text-buffer', file: 'src/range.coffee'}
+      {repo: 'theorist',    file: 'src/model.coffee'}
+    ]
+
+    async.map includes, downloadFileFromRepo, (error, includePaths) ->
+      if error?
+        done(error)
+      else
+        args = [
+          commonArgs...
+          '--title', 'Atom API Documentation'
+          '-o', 'docs/output/api'
+          '-r', 'docs/README.md'
+          'src/'
+          includePaths...
+        ]
+        grunt.util.spawn({cmd, args, opts}, done)
 
   grunt.registerTask 'lint-docs', 'Generate stats about the doc coverage', ->
     done = @async()

docs/README.md

@@ -0,0 +1,31 @@
+# Welcome to the Atom API Documentation
+
+![Atom](http://i.imgur.com/OrTvUAD.png)
+
+## FAQ
+
+### Where do I start?
+
+Check out [EditorView][EditorView] and [Editor][Editor] classes for a good
+overview of the main editor API.
+
+### How do I access these classes?
+
+Check out the [Atom][Atom] class docs to see what globals are available and
+what they provide.
+
+You can also require many of these classes in your packages via:
+
+```coffee
+{EditorView} = require 'atom'
+```
+
+### How do I create a package?
+
+You probably want to read the [creating a package][creating-a-package]
+doc first and come back here when you are done.
+
+[Atom]: ../classes/Atom.html
+[Editor]: ../classes/Editor.html
+[EditorView]: ../classes/EditorView.html
+[creating-a-package]: https://www.atom.io/docs/latest/creating-a-package

docs/creating-a-package.md

@@ -44,13 +44,13 @@ key mappings your package needs to load. If not specified, mappings in the
 _keymaps_ directory are added alphabetically.
 - `menus`(**Optional**): an Array of Strings identifying the order of
 the menu mappings your package needs to load. If not specified, mappings
-in the _keymap_ directory are added alphabetically.
+in the _menus_ directory are added alphabetically.
 - `snippets` (**Optional**): an Array of Strings identifying the order of the
 snippets your package needs to load. If not specified, snippets in the
 _snippets_ directory are added alphabetically.
 - `activationEvents` (**Optional**): an Array of Strings identifying events that
 trigger your package's activation. You can delay the loading of your package
-until one of these events is trigged.
+until one of these events is triggered.
 
 ## Source Code
 
@@ -172,7 +172,7 @@ specify which menus to load and in what order.
 It's recommended that you create an application menu item for common actions
 with your package that aren't tied to a specific element:
 
-```coffee-script
+```coffeescript
 'menu': [
   {
     'label': 'Packages'
@@ -202,7 +202,7 @@ by other packages in the order which they were loaded.
 It's recommended to specify a context menu item for commands that are linked to
 specific parts of the interface, like adding a file in the tree-view:
 
-```coffee-script
+```coffeescript
 'context-menu':
   '.tree-view':
     'Add file': 'tree-view:add-file'

package.json

@@ -49,7 +49,7 @@
     "serializable": "1.x",
     "space-pen": "3.1.1",
     "temp": "0.5.0",
-    "text-buffer": "0.15.0",
+    "text-buffer": "0.16.0",
     "theorist": "1.x",
     "underscore-plus": "1.x",
     "vm-compatibility-layer": "0.1.0"

src/directory.coffee

@@ -84,7 +84,7 @@ class Directory
 
   # Public: Reads file entries in this directory from disk synchronously.
   #
-  # Returns an Array of {File} and {Directory} objects.
+  # Returns an {Array} of {File} and {Directory} objects.
   getEntriesSync: ->
     directories = []
     files = []
@@ -103,7 +103,7 @@ class Directory
   # Public: Reads file entries in this directory from disk asynchronously.
   #
   # * callback: A function to call with an Error as the first argument and
-  #   an Array of {File} and {Directory} objects as the second argument.
+  #   an {Array} of {File} and {Directory} objects as the second argument.
   getEntries: (callback) ->
     fs.list @path, (error, entries) ->
       return callback(error) if error?

src/editor.coffee

@@ -314,16 +314,16 @@ class Editor extends Model
   # {Delegates to: TextBuffer.getPath}
   getPath: -> @buffer.getPath()
 
-  # {Delegates to: TextBuffer.getText}
+  # Public: Returns a {String} representing the entire contents of the editor.
   getText: -> @buffer.getText()
 
-  # {Delegates to: TextBuffer.setText}
+  # Public: Replaces the entire contents of the buffer with the given {String}.
   setText: (text) -> @buffer.setText(text)
 
-   # {Delegates to: TextBuffer.getTextInRange}
+  # Public: Returns a {String} of text in the given {Range}.
   getTextInRange: (range) -> @buffer.getTextInRange(range)
 
-  # {Delegates to: TextBuffer.getLineCount}
+  # Public: Returns a {Number} representing the number of lines in the editor.
   getLineCount: -> @buffer.getLineCount()
 
   # Private: Retrieves the current {TextBuffer}.
@@ -347,16 +347,28 @@ class Editor extends Model
   # {Delegates to: TextBuffer.getEofPosition}
   getEofBufferPosition: -> @buffer.getEofPosition()
 
-  # {Delegates to: TextBuffer.getLastRow}
+  # Public: Returns a {Number} representing the last zero-indexed buffer row
+  # number of the editor.
   getLastBufferRow: -> @buffer.getLastRow()
 
-  # {Delegates to: TextBuffer.rangeForRow}
+  # Public: Returns the range for the given buffer row.
+  #
+  # * row: A row {Number}.
+  # * options: An options hash with an `includeNewline` key.
+  #
+  # Returns a {Range}.
   bufferRangeForBufferRow: (row, options) -> @buffer.rangeForRow(row, options)
 
-  # {Delegates to: TextBuffer.lineForRow}
+  # Public: Returns a {String} representing the contents of the line at the
+  # given buffer row.
+  #
+  # * row - A {Number} representing a zero-indexed buffer row.
   lineForBufferRow: (row) -> @buffer.lineForRow(row)
 
-  # {Delegates to: TextBuffer.lineLengthForRow}
+  # Public: Returns a {Number} representing the line length for the given
+  # buffer row, exclusive of its line-ending character(s).
+  #
+  # row - A {Number} indicating the buffer row.
   lineLengthForBufferRow: (row) -> @buffer.lineLengthForRow(row)
 
   # {Delegates to: TextBuffer.scan}

src/git.coffee

@@ -7,7 +7,7 @@ GitUtils = require 'git-utils'
 # Public: Represents the underlying git operations performed by Atom.
 #
 # This class shouldn't be instantiated directly but instead by accessing the
-# global project instance and calling `getRepo()`.
+# `atom.project` global and calling `getRepo()`.
 #
 # ## Example
 #

src/project.coffee

@@ -308,7 +308,7 @@ class Project extends Model
   # * regex: A RegExp to search with
   # * replacementText: Text to replace all matches of regex with
   # * filePaths: List of file path strings to run the replace on.
-  # * iterator: A Function callback on each file with replacements. ({filePath, replacements}) ->
+  # * iterator: A Function callback on each file with replacements. `({filePath, replacements}) ->`
   replace: (regex, replacementText, filePaths, iterator) ->
     deferred = Q.defer()