diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab19877b4..2afb8ac19 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,7 +30,7 @@ in the proper package's repository. * Follow the [CoffeeScript](#coffeescript-styleguide), [JavaScript](https://github.com/styleguide/javascript), and [CSS](https://github.com/styleguide/css) styleguides - * Include thoughtfully worded [Jasmine](http://pivotal.github.com/jasmine/) + * Include thoughtfully worded [Jasmine](http://pivotal.github.com/jasmine) specs * Avoid placing files in `vendor`. 3rd-party packages should be added as a `package.json` dependency. @@ -61,3 +61,32 @@ in the proper package's repository. * Set parameter defaults without spaces around the equal sign * `clear = (count=1) ->` instead of `clear = (count = 1) ->` + +## Documentation Styleguide + +* Use [TomDoc](http://tomdoc.org). +* Use [Markdown](https://daringfireball.net/projects/markdown). +* Reference classes with `{ClassName}` style notation. +* Reference methods with `{ClassName.methodName}` style notation. +* Delegate to comments elsewhere with `{Delegates to: ClassName.methodName}` + style notation. + +### Example + +```coffee +# Public: Disable the package with the given name. +# +# This method emits multiple events: +# +# * `package-will-be-disabled` - before the package is disabled. +# * `package-disabled` - after the package is disabled. +# +# name - The {String} name of the package to disable. +# options - The {Object} with disable options (default: {}): +# :trackTime - `true` to track the amount of time disabling took. +# :ignoreErrors - `true` to catch and ignore errors thrown. +# callback - The {Function} to call after the package has been disabled. +# +# Returns `undefined`. +disablePackage: (name, options, callback) -> +``` diff --git a/build/package.json b/build/package.json index a687f05c7..c3a6e3811 100644 --- a/build/package.json +++ b/build/package.json @@ -7,7 +7,7 @@ }, "dependencies": { "async": "~0.2.9", - "biscotto": "0.2.0", + "biscotto": "0.6.0", "first-mate": "1.x", "formidable": "~1.0.14", "fs-plus": "1.x", diff --git a/docs/proposals/atom-docs.md b/docs/proposals/atom-docs.md deleted file mode 100644 index f3b6a0ec9..000000000 --- a/docs/proposals/atom-docs.md +++ /dev/null @@ -1,63 +0,0 @@ -## Atom Documentation Format - -This document describes our documentation format, which is markdown with -a few rules. - -### Philosophy - -1. Method and argument names **should** clearly communicate its use. -1. Use documentation to enhance and not correct method/argument names. - -#### Basic - -In some cases all that's required is a single line. **Do not** feel -obligated to write more because we have a format. - -```markdown -# Private: Returns the number of pixels from the top of the screen. -``` - -* **Each method should declare whether it's public or private by using `Public:` -or `Private:`** prefix. -* Following the colon, there should be a short description (that isn't redundant with the -method name). -* Documentation should be hard wrapped to 80 columns. - -### Public vs Private - -If a method is public it can be used by other classes (and possibly by -the public API). The appropriate steps should be taken to minimize the impact -when changing public methods. In some cases that might mean adding an -appropriate release note. In other cases it might mean doing the legwork to -ensure all affected packages are updated. - -#### Complex - -For complex methods it's necessary to explain exactly what arguments -are required and how different inputs effect the operation of the -function. - -The idea is to communicate things that the API user might not know about, -so repeating information that can be gleaned from the method or argument names -is not useful. - -```markdown -# Private: Determine the accelerator for a given command. -# -# * command: -# The name of the command. -# * keystrokesByCommand: -# An {Object} whose keys are commands and the values are Arrays containing -# the keystrokes. -# * options: -# + accelerators: -# Boolean to determine whether accelerators should be shown. -# -# Returns a String containing the keystroke in a format that can be interpreted -# by atom shell to provide nice icons where available. -# -# Raises an Exception if no window is available. -``` - -* Use curly brackets `{}` to provide links to other classes. -* Use `+` for the options list. diff --git a/src/atom.coffee b/src/atom.coffee index d8d53d0c6..bc22aa661 100644 --- a/src/atom.coffee +++ b/src/atom.coffee @@ -305,31 +305,32 @@ class Atom extends Model # Calling this method without an options parameter will open a prompt to pick # a file/folder to open in the new window. # - # * options - # * pathsToOpen: A string array of paths to open + # options - An {Object} with the following keys: + # :pathsToOpen - An {Array} of {String} paths to open. open: (options) -> ipc.sendChannel('open', options) # Public: Open a confirm dialog. # - # ## Example: - # ```coffeescript + # ## Example + # + # ```coffee # atom.confirm - # message: 'How you feeling?' - # detailedMessage: 'Be honest.' - # buttons: - # Good: -> window.alert('good to hear') - # Bad: -> window.alert('bummer') + # message: 'How you feeling?' + # detailedMessage: 'Be honest.' + # buttons: + # Good: -> window.alert('good to hear') + # Bad: -> window.alert('bummer') # ``` # - # * options: - # + message: The string message to display. - # + detailedMessage: The string detailed message to display. - # + buttons: Either an array of strings or an object where the values - # are callbacks to invoke when clicked. + # options - An {Object} with the following keys: + # :message - The {String} message to display. + # :detailedMessage - The {String} detailed message to display. + # :buttons - Either an array of strings or an object where keys are + # button names and the values are callbacks to invoke when + # clicked. # - # Returns the chosen index if buttons was an array or the return of the - # callback if buttons was an object. + # Returns the chosen button index {Number} if the buttons option was an array. confirm: ({message, detailedMessage, buttons}={}) -> buttons ?= {} if _.isArray(buttons) @@ -385,10 +386,16 @@ class Atom extends Model ipc.sendChannel('call-window-method', 'hide') # Public: Set the size of current window. + # + # width - The {Number} of pixels. + # height - The {Number} of pixels. setSize: (width, height) -> ipc.sendChannel('call-window-method', 'setSize', width, height) # Public: Set the position of current window. + # + # x - The {Number} of pixels. + # y - The {Number} of pixels. setPosition: (x, y) -> ipc.sendChannel('call-window-method', 'setPosition', x, y) @@ -498,6 +505,9 @@ class Atom extends Model # # The globals will be set on the `window` object and removed after the # require completes. + # + # id - The {String} module name or path. + # globals - An {Object} to set as globals during require (default: {}) requireWithGlobals: (id, globals={}) -> existingGlobals = {} for key, value of globals diff --git a/src/buffered-process.coffee b/src/buffered-process.coffee index 7fd604f59..ed0907f3f 100644 --- a/src/buffered-process.coffee +++ b/src/buffered-process.coffee @@ -12,30 +12,27 @@ class BufferedProcess process: null killed: false - # Executes the given executable. + # Public: Executes the given executable. # - # * options - # + command: - # The path to the executable to execute. - # + args: - # The array of arguments to pass to the script (optional). - # + options: - # The options Object to pass to Node's `ChildProcess.spawn` (optional). - # + stdout: - # The callback that receives a single argument which contains the - # standard output of the script. The callback is called as data is - # received but it's buffered to ensure only complete lines are passed - # until the source stream closes. After the source stream has closed - # all remaining data is sent in a final call (optional). - # + stderr: - # The callback that receives a single argument which contains the - # standard error of the script. The callback is called as data is - # received but it's buffered to ensure only complete lines are passed - # until the source stream closes. After the source stream has closed - # all remaining data is sent in a final call (optional). - # + exit: - # The callback which receives a single argument containing the exit - # status (optional). + # options - An {Object} with the following keys: + # :command - The {String} command to execute. + # :args - The {String}} of arguments to pass to the script (optional). + # :options - The options {Object} to pass to Node's `ChildProcess.spawn` + # (optional). + # :stdout - The callback that receives a single argument which contains the + # standard output of the script. The callback is called as data is + # received but it's buffered to ensure only complete lines are + # passed until the source stream closes. After the source stream + # has closed all remaining data is sent in a final call + # (optional). + # :stderr - The callback that receives a single argument which contains the + # standard error of the script. The callback is called as data is + # received but it's buffered to ensure only complete lines are + # passed until the source stream closes. After the source stream + # has closed all remaining data is sent in a final call + # (optional). + # :exit - The callback which receives a single argument containing the exit + # status (optional). constructor: ({command, args, options, stdout, stderr, exit}={}) -> options ?= {} @process = ChildProcess.spawn(command, args, options) @@ -93,7 +90,7 @@ class BufferedProcess onLines(buffered) if buffered.length > 0 onDone() - # Public: Terminates the process. + # Public: Terminate the process. kill: -> @killed = true @process.kill() diff --git a/src/clipboard.coffee b/src/clipboard.coffee index 4a7a8eb23..82d75d2d4 100644 --- a/src/clipboard.coffee +++ b/src/clipboard.coffee @@ -11,7 +11,7 @@ class Clipboard # Creates an `md5` hash of some text. # - # * text: A {String} to hash. + # text - A {String} to hash. # # Returns a hashed {String}. md5: (text) -> @@ -22,8 +22,8 @@ class Clipboard # The metadata associated with the text is available by calling # {.readWithMetadata}. # - # * text: A {String} to store. - # * metadata: An {Object} of additional info to associate with the text. + # text - The {String} to store. + # metadata - The additional info to associate with the text. write: (text, metadata) -> @signatureForMetadata = @md5(text) @metadata = metadata @@ -38,8 +38,9 @@ class Clipboard # Public: Read the text from the clipboard and return both the text and the # associated metadata. # - # Returns an {Object} with a `text` key and a `metadata` key if it has - # associated metadata. + # Returns an {Object} with the following keys: + # :text - The {String} clipboard text. + # :metadata - The metadata stored by an earlier call to {.write}. readWithMetadata: -> text = @read() if @signatureForMetadata is @md5(text) diff --git a/src/context-menu-manager.coffee b/src/context-menu-manager.coffee index 3e73451be..40228156b 100644 --- a/src/context-menu-manager.coffee +++ b/src/context-menu-manager.coffee @@ -24,11 +24,11 @@ class ContextMenuManager # Public: Creates menu definitions from the object specified by the menu # cson API. # - # * name: The path of the file that contains the menu definitions. - # * object: The 'context-menu' object specified in the menu cson API. - # * options: - # + devMode - Determines whether the entries should only be shown when - # the window is in dev mode. + # name - The path of the file that contains the menu definitions. + # object - The 'context-menu' object specified in the menu cson API. + # options - An {Object} with the following keys: + # :devMode - Determines whether the entries should only be shown when + # the window is in dev mode. # # Returns nothing. add: (name, object, {devMode}={}) -> @@ -39,12 +39,12 @@ class ContextMenuManager # Registers a command to be displayed when the relevant item is right # clicked. # - # * selector: The css selector for the active element which should include - # the given command in its context menu. - # * definition: The object containing keys which match the menu template API. - # * options: - # + devMode: Indicates whether this command should only appear while the - # editor is in dev mode. + # selector - The css selector for the active element which should include + # the given command in its context menu. + # definition - The object containing keys which match the menu template API. + # options - An {Object} with the following keys: + # :devMode - Indicates whether this command should only appear while the + # editor is in dev mode. addBySelector: (selector, definition, {devMode}={}) -> definitions = if devMode then @devModeDefinitions else @definitions (definitions[selector] ?= []).push(definition) @@ -65,7 +65,7 @@ class ContextMenuManager # active element are listed first. The further down the list you go, the higher # up the ancestor hierarchy they match. # - # * element: The DOM element to generate the menu template for. + # element - The DOM element to generate the menu template for. menuTemplateForMostSpecificElement: (element, {devMode}={}) -> menuTemplate = @definitionsForElement(element, {devMode}) if element.parentElement diff --git a/src/cursor.coffee b/src/cursor.coffee index 6300170f5..6b3747479 100644 --- a/src/cursor.coffee +++ b/src/cursor.coffee @@ -56,12 +56,11 @@ class Cursor # Public: Moves a cursor to a given screen position. # - # * screenPosition: - # An {Array} of two numbers: the screen row, and the screen column. - # * options: - # + autoscroll: - # A Boolean which, if `true`, scrolls the {Editor} to wherever the - # cursor moves to. + # screenPosition - An {Array} of two numbers: the screen row, and the screen + # column. + # options - An {Object} with the following keys: + # :autoscroll - A Boolean which, if `true`, scrolls the {Editor} to wherever + # the cursor moves to. setScreenPosition: (screenPosition, options={}) -> @changePosition options, => @marker.setHeadScreenPosition(screenPosition, options) @@ -72,12 +71,11 @@ class Cursor # Public: Moves a cursor to a given buffer position. # - # * bufferPosition: - # An {Array} of two numbers: the buffer row, and the buffer column. - # * options: - # + autoscroll: - # A Boolean which, if `true`, scrolls the {Editor} to wherever the - # cursor moves to. + # bufferPosition - An {Array} of two numbers: the buffer row, and the buffer + # column. + # options - An {Object} with the following keys: + # :autoscroll - A Boolean which, if `true`, scrolls the {Editor} to wherever + # the cursor moves to. setBufferPosition: (bufferPosition, options={}) -> @changePosition options, => @marker.setHeadBufferPosition(bufferPosition, options) @@ -102,11 +100,11 @@ class Cursor # Public: Get the RegExp used by the cursor to determine what a "word" is. # - # * options: - # + includeNonWordCharacters: - # A Boolean indicating whether to include non-word characters in the regex. + # options: An {Object} with the following keys: + # :includeNonWordCharacters - A {Boolean} indicating whether to include + # non-word characters in the regex. # - # Returns a RegExp. + # Returns a {RegExp}. wordRegExp: ({includeNonWordCharacters}={})-> includeNonWordCharacters ?= true nonWordCharacters = atom.config.get('editor.nonWordCharacters') @@ -120,7 +118,7 @@ class Cursor # # "Last" is defined as the most recently added cursor. # - # Returns a Boolean. + # Returns a {Boolean}. isLastCursor: -> this == @editor.getCursor() @@ -129,7 +127,7 @@ class Cursor # "Surrounded" here means that all characters before and after the cursor is # whitespace. # - # Returns a Boolean. + # Returns a {Boolean}. isSurroundedByWhitespace: -> {row, column} = @getBufferPosition() range = [[row, Math.min(0, column - 1)], [row, Math.max(0, column + 1)]] @@ -215,9 +213,9 @@ class Cursor # Public: Moves the cursor left one screen column. # - # * options: - # + moveToEndOfSelection: - # if true, move to the left of the selection if a selection exists. + # options - An {Object} with the following keys: + # :moveToEndOfSelection - if true, move to the left of the selection if a + # selection exists. moveLeft: ({moveToEndOfSelection}={}) -> range = @marker.getScreenRange() if moveToEndOfSelection and not range.isEmpty() @@ -229,9 +227,9 @@ class Cursor # Public: Moves the cursor right one screen column. # - # * options: - # + moveToEndOfSelection: - # if true, move to the right of the selection if a selection exists. + # options - An {Object} with the following keys: + # :moveToEndOfSelection - if true, move to the right of the selection if a + # selection exists. moveRight: ({moveToEndOfSelection}={}) -> range = @marker.getScreenRange() if moveToEndOfSelection and not range.isEmpty() @@ -311,12 +309,12 @@ class Cursor # Public: Retrieves the buffer position of where the current word starts. # - # * options: - # + wordRegex: - # A RegExp indicating what constitutes a "word" (default: {.wordRegExp}) - # + includeNonWordCharacters: - # A Boolean indicating whether to include non-word characters in the - # default word regex. Has no effect if wordRegex is set. + # options - An {Object} with the following keys: + # :wordRegex - A {RegExp} indicating what constitutes a "word" + # (default: {.wordRegExp}). + # :includeNonWordCharacters - A {Boolean} indicating whether to include + # non-word characters in the default word regex. + # Has no effect if wordRegex is set. # # Returns a {Range}. getBeginningOfCurrentWordBufferPosition: (options = {}) -> @@ -379,12 +377,12 @@ class Cursor # Public: Retrieves the buffer position of where the current word ends. # - # * options: - # + wordRegex: - # A RegExp indicating what constitutes a "word" (default: {.wordRegExp}) - # + includeNonWordCharacters: - # A Boolean indicating whether to include non-word characters in the - # default word regex. Has no effect if wordRegex is set. + # options - An {Object} with the following keys: + # :wordRegex - A {RegExp} indicating what constitutes a "word" + # (default: {.wordRegExp}) + # :includeNonWordCharacters - A Boolean indicating whether to include + # non-word characters in the default word regex. + # Has no effect if wordRegex is set. # # Returns a {Range}. getEndOfCurrentWordBufferPosition: (options = {}) -> @@ -403,9 +401,9 @@ class Cursor # Public: Retrieves the buffer position of where the next word starts. # - # * options: - # + wordRegex: - # A RegExp indicating what constitutes a "word" (default: {.wordRegExp}) + # options - + # :wordRegex - A {RegExp} indicating what constitutes a "word" + # (default: {.wordRegExp}). # # Returns a {Range}. getBeginningOfNextWordBufferPosition: (options = {}) -> @@ -422,9 +420,9 @@ class Cursor # Public: Returns the buffer Range occupied by the word located under the cursor. # - # * options: - # + wordRegex: - # A RegExp indicating what constitutes a "word" (default: {.wordRegExp}) + # options - + # :wordRegex - A {RegExp} indicating what constitutes a "word" + # (default: {.wordRegExp}). getCurrentWordBufferRange: (options={}) -> startOptions = _.extend(_.clone(options), allowPrevious: false) endOptions = _.extend(_.clone(options), allowNext: false) @@ -432,9 +430,9 @@ class Cursor # Public: Returns the buffer Range for the current line. # - # * options: - # + includeNewline: - # A boolean which controls whether the Range should include the newline. + # options - + # :includeNewline: - A {Boolean} which controls whether the Range should + # include the newline. getCurrentLineBufferRange: (options) -> @editor.bufferRangeForBufferRow(@getBufferRow(), options) diff --git a/src/deserializer-manager.coffee b/src/deserializer-manager.coffee index f97d9ef37..4dde07594 100644 --- a/src/deserializer-manager.coffee +++ b/src/deserializer-manager.coffee @@ -19,18 +19,29 @@ class DeserializerManager @deferredDeserializers = {} # Public: Register the given class(es) as deserializers. - add: (klasses...) -> - @deserializers[klass.name] = klass for klass in klasses + # + # classes - One or more classes to register. + add: (classes...) -> + @deserializers[klass.name] = klass for klass in classes # Public: Add a deferred deserializer for the given class name. + # + # name - The {String} name of the deserializer. + # fn - The {Function} that creates the deserializer. addDeferred: (name, fn) -> @deferredDeserializers[name] = fn # Public: Remove the given class(es) as deserializers. - remove: (klasses...) -> - delete @deserializers[klass.name] for klass in klasses + # + # classes - One or more classes to remove. + remove: (classes...) -> + delete @deserializers[name] for {name} in classes # Public: Deserialize the state and params. + # + # state - The state {Object} to deserialize. + # params - The params {Object} to pass as the second arguments to the + # deserialize method of the deserializer. deserialize: (state, params) -> return unless state? @@ -42,6 +53,8 @@ class DeserializerManager console.warn "No deserializer found for", state # Get the deserializer for the state. + # + # state - The state {Object} being deserialized. get: (state) -> return unless state? diff --git a/src/directory.coffee b/src/directory.coffee index fea9e3f9f..790de62f6 100644 --- a/src/directory.coffee +++ b/src/directory.coffee @@ -7,7 +7,7 @@ pathWatcher = require 'pathwatcher' File = require './file' -# Public: Represents a directory using {File}s. +# Public: Represents a directory on disk. # # ## Requiring in packages # @@ -18,15 +18,12 @@ module.exports = class Directory Emitter.includeInto(this) - path: null realPath: null # Public: Configures a new Directory instance, no files are accessed. # - # * path: - # A String containing the absolute path to the directory. - # + symlink: - # A Boolean indicating if the path is a symlink (defaults to false). + # path - A {String} containing the absolute path to the directory. + # symlink - A {Boolean} indicating if the path is a symlink (default: false). constructor: (@path, @symlink=false) -> @on 'first-contents-changed-subscription-will-be-added', => # Triggered by emissary, when a new contents-changed listener attaches @@ -36,7 +33,7 @@ class Directory # Triggered by emissary, when the last contents-changed listener detaches @unsubscribeFromNativeChangeEvents() - # Public: Returns the basename of the directory. + # Public: Returns the {String} basename of the directory. getBaseName: -> path.basename(@path) @@ -108,8 +105,8 @@ 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. + # callback - A {Function} to call with an {Error} as the 1st argument and + # an {Array} of {File} and {Directory} objects as the 2nd argument. getEntries: (callback) -> fs.list @path, (error, entries) -> return callback(error) if error? diff --git a/src/editor-view.coffee b/src/editor-view.coffee index f4334843a..19636802a 100644 --- a/src/editor-view.coffee +++ b/src/editor-view.coffee @@ -276,12 +276,11 @@ class EditorView extends View # Public: Defines which characters are invisible. # - # invisibles - An {Object} defining the invisible characters. - # The defaults are: - # eol: `\u00ac` - # space: `\u00b7` - # tab: `\u00bb` - # cr: `\u00a4` + # invisibles - An {Object} defining the invisible characters: + # :eol - The end of line invisible {String} (default: `\u00ac`). + # :space - The space invisible {String} (default: `\u00b7`). + # :tab - The tab invisible {String} (default: `\u00bb`). + # :cr - The carriage return invisible {String} (default: `\u00a4`). setInvisibles: (@invisibles={}) -> _.defaults @invisibles, eol: '\u00ac' @@ -627,8 +626,8 @@ class EditorView extends View # an {Object} (`{row, column}`), {Array} (`[row, column]`), or # {Point}. # options - A hash with the following keys: - # center - if `true`, the position is scrolled such that it's in - # the center of the editor + # :center - if `true`, the position is scrolled such that it's in + # the center of the editor scrollToPixelPosition: (pixelPosition, options) -> return unless @attached @scrollVertically(pixelPosition, options) diff --git a/src/editor.coffee b/src/editor.coffee index eaf66fd81..3befee1f8 100644 --- a/src/editor.coffee +++ b/src/editor.coffee @@ -238,8 +238,7 @@ class Editor extends Model # or if its column goes beyond a line's length, this "sanitizes" the value # to a real position. # - # * bufferPosition: - # The {Point} to clip + # bufferPosition - The {Point} to clip. # # Returns the new, clipped {Point}. Note that this could be the same as # `bufferPosition` if no clipping was performed. @@ -251,8 +250,7 @@ class Editor extends Model # or if its column goes beyond a line's length, this "sanitizes" the value # to a real range. # - # * range: - # The {Range} to clip + # range - The {Range} to clip. # # Returns the new, clipped {Range}. Note that this could be the same as # `range` if no clipping was performed. @@ -260,17 +258,14 @@ class Editor extends Model # Public: Returns the indentation level of the given a buffer row # - # * bufferRow: - # A Number indicating the buffer row. + # bufferRow - A {Number} indicating the buffer row. indentationForBufferRow: (bufferRow) -> @indentLevelForLine(@lineForBufferRow(bufferRow)) # Public: Sets the indentation level for the given buffer row. # - # * bufferRow: - # A {Number} indicating the buffer row. - # * newLevel: - # A {Number} indicating the new indentation level. + # bufferRow - A {Number} indicating the buffer row. + # newLevel - A {Number} indicating the new indentation level. setIndentationForBufferRow: (bufferRow, newLevel) -> currentIndentLength = @lineForBufferRow(bufferRow).match(/^\s*/)[0].length newIndentString = @buildIndentString(newLevel) @@ -278,8 +273,7 @@ class Editor extends Model # Public: Returns the indentation level of the given line of text. # - # * line: - # A {String} in the current buffer. + # line - A {String} in the current buffer. # # Returns a {Number} or 0 if the text isn't found within the buffer. indentLevelForLine: (line) -> @@ -349,8 +343,8 @@ class Editor extends Model # Public: Returns the range for the given buffer row. # - # * row: A row {Number}. - # * options: An options hash with an `includeNewline` key. + # row - A row {Number}. + # options - An options hash with an `includeNewline` key. # # Returns a {Range}. bufferRangeForBufferRow: (row, options) -> @buffer.rangeForRow(row, options) @@ -358,7 +352,7 @@ class Editor extends Model # Public: Returns a {String} representing the contents of the line at the # given buffer row. # - # * row - A {Number} representing a zero-indexed buffer row. + # row - A {Number} representing a zero-indexed buffer row. lineForBufferRow: (row) -> @buffer.lineForRow(row) # Public: Returns a {Number} representing the line length for the given @@ -433,10 +427,8 @@ class Editor extends Model # Public: Inserts text at the current cursor positions # - # * text: - # A String representing the text to insert. - # * options: - # + A set of options equivalent to {Selection.insertText} + # text - A {String} representing the text to insert. + # options - A set of options equivalent to {Selection.insertText}. insertText: (text, options={}) -> options.autoIndentNewline ?= @shouldAutoIndent() options.autoDecreaseIndent ?= @shouldAutoIndent() @@ -463,8 +455,7 @@ class Editor extends Model # Public: Indents the current line. # - # * options - # + A set of options equivalent to {Selection.indent}. + # options - A set of options equivalent to {Selection.indent}. indent: (options={})-> options.autoIndent ?= @shouldAutoIndent() @mutateSelectedText (selection) -> selection.indent(options) @@ -552,8 +543,7 @@ class Editor extends Model # Public: Pastes the text in the clipboard. # - # * options: - # + A set of options equivalent to {Selection.insertText}. + # options - A set of options equivalent to {Selection.insertText}. pasteText: (options={}) -> {text, metadata} = atom.clipboard.readWithMetadata() @@ -820,10 +810,8 @@ class Editor extends Model # Public: Creates a new selection at the given marker. # - # * marker: - # The {DisplayBufferMarker} to highlight - # * options: - # + A hash of options that pertain to the {Selection} constructor. + # marker - The {DisplayBufferMarker} to highlight + # options - An {Object} that pertains to the {Selection} constructor. # # Returns the new {Selection}. addSelection: (marker, options={}) -> @@ -844,10 +832,8 @@ class Editor extends Model # Public: Given a buffer range, this adds a new selection for it. # - # * bufferRange: - # A {Range} in the buffer - # * options: - # + A hash of options for {.markBufferRange} + # bufferRange - A {Range} in the buffer. + # options - An options {Object} for {.markBufferRange}. # # Returns the new {Selection}. addSelectionForBufferRange: (bufferRange, options={}) -> @@ -857,20 +843,16 @@ class Editor extends Model # Public: Given a buffer range, this removes all previous selections and # creates a new selection for it. # - # * bufferRange: - # A {Range} in the buffer - # * options: - # + A hash of options for {.setSelectedBufferRanges} + # bufferRange - A {Range} in the buffer. + # options - An options {Object} for {.setSelectedBufferRanges}. setSelectedBufferRange: (bufferRange, options) -> @setSelectedBufferRanges([bufferRange], options) # Public: Given an array of buffer ranges, this removes all previous # selections and creates new selections for them. # - # * bufferRange: - # A {Range} in the buffer - # * options: - # + A hash of options for {.setSelectedBufferRanges} + # bufferRange - A {Range} in the buffer. + # options - An options {Object} for {.setSelectedBufferRanges}. setSelectedBufferRanges: (bufferRanges, options={}) -> throw new Error("Passed an empty array to setSelectedBufferRanges") unless bufferRanges.length @@ -887,7 +869,7 @@ class Editor extends Model # Public: Unselects a given selection. # - # * selection - The {Selection} to remove. + # selection - The {Selection} to remove. removeSelection: (selection) -> _.remove(@selections, selection) @@ -898,9 +880,7 @@ class Editor extends Model @consolidateSelections() @getSelection().clear() - # Public: - # - # Removes all but one cursor (if there are multiple cursors) + # Removes all but one cursor (if there are multiple cursors). consolidateSelections: -> selections = @getSelections() if selections.length > 1 @@ -937,8 +917,7 @@ class Editor extends Model # Public: Determines if a given buffer range is included in a {Selection}. # - # * bufferRange: - # The {Range} you're checking against + # bufferRange - The {Range} you're checking against. # # Returns a {Boolean}. selectionIntersectsBufferRange: (bufferRange) -> @@ -947,10 +926,8 @@ class Editor extends Model # Public: Moves every local cursor to a given screen position. # - # * position: - # An {Array} of two numbers: the screen row, and the screen column. - # * options: - # An object with properties based on {Cursor.setScreenPosition} + # position - An {Array} of two numbers: the screen row, and the screen column. + # options - An {Object} with properties based on {Cursor.setScreenPosition}. setCursorScreenPosition: (position, options) -> @moveCursors (cursor) -> cursor.setScreenPosition(position, options) @@ -969,10 +946,8 @@ class Editor extends Model # Public: Moves every cursor to a given buffer position. # - # * position: - # An {Array} of two numbers: the buffer row, and the buffer column. - # * options: - # + An object with properties based on {Cursor.setBufferPosition} + # position - An {Array} of two numbers: the buffer row, and the buffer column. + # options - An object with properties based on {Cursor.setBufferPosition}. setCursorBufferPosition: (position, options) -> @moveCursors (cursor) -> cursor.setBufferPosition(position, options) @@ -1015,9 +990,8 @@ class Editor extends Model # Public: Returns the word under the most recently added local {Cursor}. # - # * options: - # + An object with properties based on - # {Cursor.getBeginningOfCurrentWordBufferPosition}. + # options - An object with properties based on + # {Cursor.getBeginningOfCurrentWordBufferPosition}. getWordUnderCursor: (options) -> @getTextInBufferRange(@getCursor().getCurrentWordBufferRange(options)) @@ -1092,8 +1066,7 @@ class Editor extends Model # Public: Selects the text from the current cursor position to a given screen # position. # - # * position: - # An instance of {Point}, with a given `row` and `column`. + # position - An instance of {Point}, with a given `row` and `column`. selectToScreenPosition: (position) -> lastSelection = @getLastSelection() lastSelection.selectToScreenPosition(position) @@ -1252,8 +1225,6 @@ class Editor extends Model @setSelectedBufferRange(range) range - # Public: - # # FIXME: Not sure how to describe what this does. mergeCursors: -> positions = [] @@ -1264,22 +1235,16 @@ class Editor extends Model else positions.push(position) - # Public: - # # FIXME: Not sure how to describe what this does. expandSelectionsForward: (fn) -> @mergeIntersectingSelections => fn(selection) for selection in @getSelections() - # Public: - # # FIXME: Not sure how to describe what this does. expandSelectionsBackward: (fn) -> @mergeIntersectingSelections isReversed: true, => fn(selection) for selection in @getSelections() - # Public: - # # FIXME: No idea what this does. finalizeSelections: -> selection.finalize() for selection in @getSelections() diff --git a/src/file.coffee b/src/file.coffee index efab0b96f..beedf73f8 100644 --- a/src/file.coffee +++ b/src/file.coffee @@ -25,10 +25,8 @@ class File # Public: Creates a new file. # - # * path: - # A String containing the absolute path to the file - # * symlink: - # A Boolean indicating if the path is a symlink (default: false) + # path - A {String} containing the absolute path to the file + # symlink - A {Boolean} indicating if the path is a symlink (default: false). constructor: (@path, @symlink=false) -> throw new Error("#{@path} is a directory") if fs.isDirectorySync(@path) @@ -52,10 +50,10 @@ class File # Sets the path for the file. setPath: (@path) -> - # Public: Returns the path for the file. + # Public: Returns the {String} path for the file. getPath: -> @path - # Public: Return the filename without any directory information. + # Public: Return the {String} filename without any directory information. getBaseName: -> path.basename(@path) @@ -80,9 +78,8 @@ class File # Public: Reads the contents of the file. # - # * flushCache: - # A Boolean indicating whether to require a direct read or if a cached - # copy is acceptable. + # flushCache - A {Boolean} indicating whether to require a direct read or if + # a cached copy is acceptable. # # Returns a promise that resovles to a String. read: (flushCache) -> diff --git a/src/keymap.coffee b/src/keymap.coffee index 1f71f3ff3..8fccf060d 100644 --- a/src/keymap.coffee +++ b/src/keymap.coffee @@ -43,10 +43,8 @@ class Keymap # Public: Returns a array of {KeyBinding}s (sorted by selector specificity) # that match a keystroke and element. # - # * keystroke: - # The string representing the keys pressed (e.g. ctrl-P). - # * element: - # The DOM node that will match a {KeyBinding}'s selector. + # keystroke - The {String} representing the keys pressed (e.g. ctrl-P). + # element - The DOM node that will match a {KeyBinding}'s selector. keyBindingsForKeystrokeMatchingElement: (keystroke, element) -> keyBindings = @keyBindingsForKeystroke(keystroke) @keyBindingsMatchingElement(element, keyBindings) @@ -54,41 +52,37 @@ class Keymap # Public: Returns a array of {KeyBinding}s (sorted by selector specificity) # that match a command. # - # * command: - # The string representing the command (tree-view:toggle) - # * element: - # The DOM node that will match a {KeyBinding}'s selector. + # command - The {String} representing the command (tree-view:toggle). + # element - The DOM node that will match a {KeyBinding}'s selector. keyBindingsForCommandMatchingElement: (command, element) -> keyBindings = @keyBindingsForCommand(command) @keyBindingsMatchingElement(element, keyBindings) # Public: Returns an array of {KeyBinding}s that match a keystroke - # * keystroke: - # The string representing the keys pressed (e.g. ctrl-P) + # + # keystroke: The {String} representing the keys pressed (e.g. ctrl-P) keyBindingsForKeystroke: (keystroke) -> keystroke = KeyBinding.normalizeKeystroke(keystroke) @keyBindings.filter (keyBinding) -> keyBinding.matches(keystroke) # Public: Returns an array of {KeyBinding}s that match a command - # * keystroke: - # The string representing the keys pressed (e.g. ctrl-P) + # + # keystroke - The {String} representing the keys pressed (e.g. ctrl-P) keyBindingsForCommand: (command) -> @keyBindings.filter (keyBinding) -> keyBinding.command == command # Public: Returns a array of {KeyBinding}s (sorted by selector specificity) # whos selector matches the element. # - # * element: - # The DOM node that will match a {KeyBinding}'s selector. + # element - The DOM node that will match a {KeyBinding}'s selector. keyBindingsMatchingElement: (element, keyBindings=@keyBindings) -> keyBindings = keyBindings.filter ({selector}) -> $(element).closest(selector).length > 0 keyBindings.sort (a, b) -> a.compare(b) # Public: Returns a keystroke string derived from an event. - # * event: - # A DOM or jQuery event - # * previousKeystroke: - # An optional string used for multiKeystrokes + # + # event - A DOM or jQuery event. + # previousKeystroke - An optional string used for multiKeystrokes. keystrokeStringForEvent: (event, previousKeystroke) -> if event.originalEvent.keyIdentifier.indexOf('U+') == 0 hexCharCode = event.originalEvent.keyIdentifier[2..] diff --git a/src/menu-manager.coffee b/src/menu-manager.coffee index 484a7f98f..710d7e377 100644 --- a/src/menu-manager.coffee +++ b/src/menu-manager.coffee @@ -19,9 +19,20 @@ class MenuManager # Public: Adds the given item definition to the existing template. # - # * item: - # An object which describes a menu item as defined by - # https://github.com/atom/atom-shell/blob/master/docs/api/browser/menu.md + # ## Example + # ```coffee + # atom.menu.add [ + # { + # label: 'Hello' + # submenu : [{label: 'World!', command: 'hello:world'}] + # } + # ] + # ``` + # + # items - An {Array} of menu item {Object}s containing the keys: + # :label - The {String} menu label. + # :submenu - An optional {Array} of sub menu items. + # :command - An option {String} command to trigger when the item is clicked. # # Returns nothing. add: (items) -> @@ -31,7 +42,7 @@ class MenuManager # Should the binding for the given selector be included in the menu # commands. # - # * selector: A String selector to check. + # selector - A {String} selector to check. # # Returns true to include the selector, false otherwise. includeSelector: (selector) -> diff --git a/src/package-manager.coffee b/src/package-manager.coffee index 9db92f4e9..cecf5c589 100644 --- a/src/package-manager.coffee +++ b/src/package-manager.coffee @@ -181,7 +181,7 @@ class PackageManager # Get packages for a certain package type # - # * types: an {Array} of {String}s like ['atom', 'textmate'] + # types - an {Array} of {String}s like ['atom', 'textmate']. getLoadedPackagesForTypes: (types) -> pack for pack in @getLoadedPackages() when pack.getType() in types diff --git a/src/pane.coffee b/src/pane.coffee index 4ebeb5ea7..a3d2be56c 100644 --- a/src/pane.coffee +++ b/src/pane.coffee @@ -121,11 +121,9 @@ class Pane extends Model # Public: Adds the item to the pane. # - # * item: - # The item to add. It can be a model with an associated view or a view. - # * index: - # An optional index at which to add the item. If omitted, the item is - # added after the current active item. + # item - The item to add. It can be a model with an associated view or a view. + # index - An optional index at which to add the item. If omitted, the item is + # added after the current active item. # # Returns the added item addItem: (item, index=@getActiveItemIndex() + 1) -> @@ -138,12 +136,11 @@ class Pane extends Model # Public: Adds the given items to the pane. # - # * items: - # An {Array} of items to add. Items can be models with associated views - # or views. Any items that are already present in items will not be added. - # * index: - # An optional index at which to add the item. If omitted, the item is - # added after the current active item. + # items - An {Array} of items to add. Items can be models with associated + # views or views. Any items that are already present in items will + # not be added. + # index - An optional index at which to add the item. If omitted, the item is + # added after the current active item. # # Returns an {Array} of the added items addItems: (items, index=@getActiveItemIndex() + 1) -> @@ -237,8 +234,9 @@ class Pane extends Model # Public: Saves the specified item. # - # * item: The item to save. - # * nextAction: An optional function which will be called after the item is saved. + # item - The item to save. + # nextAction - An optional function which will be called after the item is + # saved. saveItem: (item, nextAction) -> if item?.getUri?() item.save?() @@ -248,8 +246,9 @@ class Pane extends Model # Public: Saves the given item at a prompted-for location. # - # * item: The item to save. - # * nextAction: An optional function which will be called after the item is saved. + # item - The item to save. + # nextAction - An optional function which will be called after the item is + # saved. saveItemAs: (item, nextAction) -> return unless item?.saveAs? @@ -284,8 +283,8 @@ class Pane extends Model # Public: Creates a new pane to the left of the receiver. # - # * params: - # + items: An optional array of items with which to construct the new pane. + # params - An object with keys: + # :items - An optional array of items with which to construct the new pane. # # Returns the new {Pane}. splitLeft: (params) -> @@ -293,8 +292,8 @@ class Pane extends Model # Public: Creates a new pane to the right of the receiver. # - # * params: - # + items: An optional array of items with which to construct the new pane. + # params - An object with keys: + # :items - An optional array of items with which to construct the new pane. # # Returns the new {Pane}. splitRight: (params) -> @@ -302,8 +301,8 @@ class Pane extends Model # Public: Creates a new pane above the receiver. # - # * params: - # + items: An optional array of items with which to construct the new pane. + # params - An object with keys: + # :items - An optional array of items with which to construct the new pane. # # Returns the new {Pane}. splitUp: (params) -> @@ -311,8 +310,8 @@ class Pane extends Model # Public: Creates a new pane below the receiver. # - # * params: - # + items: An optional array of items with which to construct the new pane. + # params - An object with keys: + # :items - An optional array of items with which to construct the new pane. # # Returns the new {Pane}. splitDown: (params) -> diff --git a/src/project.coffee b/src/project.coffee index 2c37ccf63..55bf2cf30 100644 --- a/src/project.coffee +++ b/src/project.coffee @@ -50,14 +50,14 @@ class Project extends Model # # An {Editor} will be used if no openers return a value. # - # ## Example: + # ## Example # ```coffeescript # atom.project.registerOpener (filePath) -> # if path.extname(filePath) is '.toml' # return new TomlEditor(filePath) # ``` # - # * opener: A function to be called when a path is being opened. + # opener - A {Function} to be called when a path is being opened. registerOpener: (opener) -> @openers.push(opener) # Public: Remove a previously registered opener. @@ -108,8 +108,7 @@ class Project extends Model # the path is already absolute or if it is prefixed with a scheme, it is # returned unchanged. # - # * uri: - # The String name of the path to convert + # uri - The {String} name of the path to convert. # # Returns a String. resolve: (uri) -> @@ -133,10 +132,8 @@ class Project extends Model # Public: Given a path to a file, this constructs and associates a new # {Editor}, showing the file. # - # * filePath: - # The {String} path of the file to associate with - # * options: - # Options that you can pass to the {Editor} constructor + # filePath - The {String} path of the file to associate with. + # options - Options that you can pass to the {Editor} constructor. # # Returns a promise that resolves to an {Editor}. open: (filePath, options={}) -> @@ -218,8 +215,8 @@ class Project extends Model # Given a file path, this sets its {TextBuffer}. # - # absoluteFilePath - A {String} representing a path - # text - The {String} text to use as a buffer + # absoluteFilePath - A {String} representing a path. + # text - The {String} text to use as a buffer. # # Returns a promise that resolves to the {TextBuffer}. buildBuffer: (absoluteFilePath) -> @@ -252,12 +249,10 @@ class Project extends Model # Public: Performs a search across all the files in the project. # - # * regex: - # A RegExp to search with - # * options: - # - paths: an {Array} of glob patterns to search within - # * iterator: - # A Function callback on each file found + # regex - A {RegExp} to search with. + # options - An optional options {Object} (default: {}): + # :paths - An {Array} of glob patterns to search within + # iterator - A {Function} callback on each file found scan: (regex, options={}, iterator) -> if _.isFunction(options) iterator = options @@ -296,10 +291,11 @@ class Project extends Model # Public: Performs a replace across all the specified files in the project. # - # * 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}) ->` + # 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}) ->`. replace: (regex, replacementText, filePaths, iterator) -> deferred = Q.defer() diff --git a/src/select-list-view.coffee b/src/select-list-view.coffee index 6119c3836..9cf1885ae 100644 --- a/src/select-list-view.coffee +++ b/src/select-list-view.coffee @@ -64,14 +64,14 @@ class SelectListView extends View # Public: Set the array of items to display in the list. # - # * array: The array of model elements to display in the list. + # array - The {Array} of model elements to display in the list. setArray: (@array=[]) -> @populateList() @setLoading() # Public: Set the error message to display. # - # * message: The error message. + # message - The {String} error message (default: ''). setError: (message='') -> if message.length is 0 @error.text('').hide() @@ -81,7 +81,7 @@ class SelectListView extends View # Public: Set the loading message to display. # - # * message: The loading message. + # message - The {String} loading message (default: ''). setLoading: (message='') -> if message.length is 0 @loading.text("") @@ -131,8 +131,8 @@ class SelectListView extends View # # Subclasses may override this method to customize the message. # - # * itemCount: The number of items in the array specified to {.setArray} - # * filteredItemCount: The number of items that pass the fuzzy filter test. + # itemCount - The {Number} of items in the array specified to {.setArray} + # filteredItemCount - The {Number} of items that pass the fuzzy filter test. getEmptyMessage: (itemCount, filteredItemCount) -> 'No matches found' selectPreviousItem: -> @@ -184,7 +184,7 @@ class SelectListView extends View # # This method should be overridden by subclasses. # - # * element: The selected model element. + # element - The selected model element. confirmed: (element) -> attach: -> diff --git a/src/selection.coffee b/src/selection.coffee index bc2162213..6f5e50788 100644 --- a/src/selection.coffee +++ b/src/selection.coffee @@ -55,10 +55,8 @@ class Selection # Public: Modifies the screen range for the selection. # - # * screenRange: - # The new {Range} to use - # * options: - # + A hash of options matching those found in {.setBufferRange} + # screenRange - The new {Range} to use. + # options - A hash of options matching those found in {.setBufferRange}. setScreenRange: (screenRange, options) -> @setBufferRange(@editor.bufferRangeForScreenRange(screenRange), options) @@ -68,13 +66,11 @@ class Selection # Public: Modifies the buffer {Range} for the selection. # - # * screenRange: - # The new {Range} to select - # * options - # + preserveFolds: - # if `true`, the fold settings are preserved after the selection moves - # + autoscroll: - # if `true`, the {Editor} scrolls to the new selection + # screenRange - The new {Range} to select. + # options - An {Object} with the keys: + # :preserveFolds - if `true`, the fold settings are preserved after the + # selection moves. + # :autoscroll - if `true`, the {Editor} scrolls to the new selection. setBufferRange: (bufferRange, options={}) -> bufferRange = Range.fromObject(bufferRange) @needsAutoscroll = options.autoscroll @@ -124,8 +120,7 @@ class Selection # Public: Selects an entire line in the buffer. # - # * row: - # The line Number to select (default: the row of the cursor) + # row - The line {Number} to select (default: the row of the cursor). selectLine: (row=@cursor.getBufferPosition().row) -> range = @editor.bufferRangeForBufferRow(row, includeNewline: true) @setBufferRange(@getBufferRange().union(range)) @@ -144,8 +139,7 @@ class Selection # Public: Selects the text from the current cursor position to a given screen # position. # - # * position: - # An instance of {Point}, with a given `row` and `column`. + # position - An instance of {Point}, with a given `row` and `column`. selectToScreenPosition: (position) -> @modifySelection => if @initialScreenRange @@ -164,8 +158,7 @@ class Selection # Public: Selects the text from the current cursor position to a given buffer # position. # - # * position: - # An instance of {Point}, with a given `row` and `column`. + # position - An instance of {Point}, with a given `row` and `column`. selectToBufferPosition: (position) -> @modifySelection => @cursor.setBufferPosition(position) @@ -255,8 +248,6 @@ class Selection @editor.addSelectionForBufferRange(range, goalBufferRange: range) break - # Public: - # # FIXME: I have no idea what this does. getGoalBufferRange: -> @marker.getAttributes().goalBufferRange @@ -281,20 +272,14 @@ class Selection # Public: Replaces text at the current selection. # - # * text: - # A {String} representing the text to add - # * options - # + select: - # if `true`, selects the newly added text - # + autoIndent: - # if `true`, indents all inserted text appropriately - # + autoIndentNewline: - # if `true`, indent newline appropriately - # + autoDecreaseIndent: - # if `true`, decreases indent level appropriately (for example, when a - # closing bracket is inserted) - # + undo: - # if `skip`, skips the undo stack for this operation. + # text - A {String} representing the text to add + # options - An {Object} with keys: + # :select - if `true`, selects the newly added text. + # :autoIndent - if `true`, indents all inserted text appropriately. + # :autoIndentNewline - if `true`, indent newline appropriately. + # :autoDecreaseIndent - if `true`, decreases indent level appropriately + # (for example, when a closing bracket is inserted). + # :undo - if `skip`, skips the undo stack for this operation. insertText: (text, options={}) -> oldBufferRange = @getBufferRange() @editor.destroyFoldsContainingBufferRow(oldBufferRange.end.row) @@ -322,10 +307,8 @@ class Selection # Public: Indents the given text to the suggested level based on the grammar. # - # * text: - # The string to indent within the selection. - # * indentBasis: - # The beginning indent level. + # text - The {String} to indent within the selection. + # indentBasis - The beginning indent level. normalizeIndents: (text, indentBasis) -> textPrecedingCursor = @cursor.getCurrentBufferLine()[0...@cursor.getBufferColumn()] isCursorInsideExistingLine = /\S/.test(textPrecedingCursor) @@ -353,10 +336,9 @@ class Selection # Public: Indents the selection. # - # * options - A hash with one key, - # + autoIndent: - # If `true`, the indentation is performed appropriately. Otherwise, - # {Editor.getTabText} is used + # options - A {Object} with the keys: + # :autoIndent - If `true`, the indentation is performed appropriately. + # Otherwise, {Editor.getTabText} is used. indent: ({ autoIndent }={})-> { row, column } = @cursor.getBufferPosition() @@ -501,25 +483,16 @@ class Selection @editor.toggleLineCommentsForBufferRows(@getBufferRowRange()...) # Public: Cuts the selection until the end of the line. - # - # * maintainClipboard: - # ? cutToEndOfLine: (maintainClipboard) -> @selectToEndOfLine() if @isEmpty() @cut(maintainClipboard) # Public: Copies the selection to the clipboard and then deletes it. - # - # * maintainClipboard: - # ? cut: (maintainClipboard=false) -> @copy(maintainClipboard) @delete() # Public: Copies the current selection to the clipboard. - # - # * maintainClipboard: - # ? copy: (maintainClipboard=false) -> return if @isEmpty() text = @editor.buffer.getTextInRange(@getBufferRange()) @@ -536,7 +509,6 @@ class Selection @editor.createFold(range.start.row, range.end.row) @cursor.setBufferPosition([range.end.row + 1, 0]) - # Public: ? modifySelection: (fn) -> @retainSelection = true @plantTail() @@ -553,8 +525,7 @@ class Selection # Public: Identifies if a selection intersects with a given buffer range. # - # * bufferRange: - # A {Range} to check against + # bufferRange - A {Range} to check against. # # Returns a Boolean. intersectsBufferRange: (bufferRange) -> @@ -562,8 +533,7 @@ class Selection # Public: Identifies if a selection intersects with another selection. # - # * otherSelection: - # A {Selection} to check against + # otherSelection - A {Selection} to check against. # # Returns a Boolean. intersectsWith: (otherSelection) -> @@ -572,10 +542,8 @@ class Selection # Public: Combines the given selection into this selection and then destroys # the given selection. # - # * otherSelection: - # A {Selection} to merge with - # * options - # + A hash of options matching those found in {.setBufferRange} + # otherSelection - A {Selection} to merge with. + # options - A hash of options matching those found in {.setBufferRange}. merge: (otherSelection, options) -> myGoalBufferRange = @getGoalBufferRange() otherGoalBufferRange = otherSelection.getGoalBufferRange() @@ -591,8 +559,7 @@ class Selection # # See {Range.compare} for more details. # - # * otherSelection: - # A {Selection} to compare with. + # otherSelection - A {Selection} to compare against. compare: (otherSelection) -> @getBufferRange().compare(otherSelection.getBufferRange()) diff --git a/src/syntax.coffee b/src/syntax.coffee index 13e12e609..881d5fa2a 100644 --- a/src/syntax.coffee +++ b/src/syntax.coffee @@ -15,7 +15,6 @@ Token = require './token' module.exports = class Syntax extends GrammarRegistry Subscriber.includeInto(this) - atom.deserializers.add(this) @deserialize: ({grammarOverridesByPath}) -> @@ -62,8 +61,8 @@ class Syntax extends GrammarRegistry # console.log(comment) # '# ' # ``` # - # * scope: An {Array} of {String} scopes. - # * keyPath: A {String} key path. + # scope - An {Array} of {String} scopes. + # keyPath - A {String} key path. # # Returns a {String} property value or undefined. getProperty: (scope, keyPath) -> diff --git a/src/task.coffee b/src/task.coffee index e4f9597d3..8e2b57277 100644 --- a/src/task.coffee +++ b/src/task.coffee @@ -24,11 +24,9 @@ class Task # Public: A helper method to easily launch and run a task once. # - # * taskPath: - # The path to the Coffeescript/Javascript file which exports a single - # function to execute. - # * args: - # The Array of arguments to pass to the exported function. + # taskPath - The {String} path to the CoffeeScript/JavaScript file which + # exports a single {Function} to execute. + # args - The arguments to pass to the exported function. @once: (taskPath, args...) -> task = new Task(taskPath) task.once 'task:completed', -> task.terminate() @@ -45,9 +43,8 @@ class Task # Public: Creates a task. # - # * taskPath: - # The path to the Coffeescript/Javascript file that exports a single - # function to execute. + # taskPath - The {String} path to the CoffeeScript/JavaScript file that + # exports a single {Function} to execute. constructor: (taskPath) -> coffeeCacheRequire = "require('#{require.resolve('./coffee-cache')}').register();" coffeeScriptRequire = "require('#{require.resolve('coffee-script')}').register();" @@ -81,21 +78,21 @@ class Task # Public: Starts the task. # - # * args: - # The Array of arguments to pass to the function exported by the script. If - # the last argument is a function, its removed from the array and called - # upon completion (and replaces the complete function on the task instance). - start: (args...) -> + # args - The arguments to pass to the function exported by this task's script. + # callback - An optional {Function} to call when the task completes. + start: (args..., callback) -> throw new Error("Cannot start terminated process") unless @childProcess? @handleEvents() - @callback = args.pop() if _.isFunction(args[args.length - 1]) + if _.isFunction(callback) + @callback = callback + else + args = arguments @send({event: 'start', args}) # Public: Send message to the task. # - # * message: - # The message to send + # message - The message to send to the task. send: (message) -> throw new Error("Cannot send message to terminated process") unless @childProcess? @childProcess.send(message) diff --git a/src/theme-manager.coffee b/src/theme-manager.coffee index 0525d3cc1..a5fa5a0c8 100644 --- a/src/theme-manager.coffee +++ b/src/theme-manager.coffee @@ -77,7 +77,7 @@ class ThemeManager # Public: Set the list of enabled themes. # - # * enabledThemeNames: An {Array} of {String} theme names. + # enabledThemeNames - An {Array} of {String} theme names. setEnabledThemes: (enabledThemeNames) -> atom.config.set('core.themes', enabledThemeNames) @@ -140,8 +140,9 @@ class ThemeManager # # This supports both CSS and LESS stylsheets. # - # * stylesheetPath: A {String} path to the stylesheet that can be an absolute - # path or a relative path that will be resolved against the load path. + # stylesheetPath - A {String} path to the stylesheet that can be an absolute + # path or a relative path that will be resolved against the + # load path. # # Returns the absolute path to the required stylesheet. requireStylesheet: (stylesheetPath, ttype = 'bundled', htmlElement) -> diff --git a/src/workspace.coffee b/src/workspace.coffee index b657031a6..eec5d88ed 100644 --- a/src/workspace.coffee +++ b/src/workspace.coffee @@ -48,9 +48,9 @@ class Workspace extends Model # Public: Asynchronously opens a given a filepath in Atom. # - # * filePath: A file path - # * options - # + initialLine: The buffer line number to open to. + # filePath - A {String} file path. + # options - An options {Object} (default: {}). + # :initialLine - The buffer line number to open to. # # Returns a promise that resolves to the {Editor} for the file URI. open: (filePath, options={}) ->