From c4cb6abef143935eb6dc5f4d03e529112a9e039b Mon Sep 17 00:00:00 2001 From: Kevin Sawicki Date: Thu, 6 Feb 2014 16:30:30 -0800 Subject: [PATCH] :memo: doc parameters in editor.coffee --- src/editor.coffee | 97 +++++++++++++++-------------------------------- 1 file changed, 31 insertions(+), 66 deletions(-) diff --git a/src/editor.coffee b/src/editor.coffee index eaf66fd81..fc79fc841 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()