From 1670357293b7088e1348d0f03e17f5bd454d43d3 Mon Sep 17 00:00:00 2001 From: Ross Allen Date: Thu, 24 Sep 2015 12:14:59 -0700 Subject: [PATCH] Link Gutter::decorateMarker to TextEditor::decorateMarker `Gutter::decorateMarker` passes its `decorationParams` object through to `TextEditor::decorateMarker`. Rather than duplicate documentation and fall out-of-date (as was surfaced in #8920), link the `TextEditor::decorateMarker` as the canonical docs location. --- src/gutter.coffee | 13 +++++-------- src/text-editor.coffee | 40 +++++++++++++++++++++++++--------------- 2 files changed, 30 insertions(+), 23 deletions(-) diff --git a/src/gutter.coffee b/src/gutter.coffee index 4f09a27f2..8418823bf 100644 --- a/src/gutter.coffee +++ b/src/gutter.coffee @@ -78,14 +78,11 @@ class Gutter # ## Arguments # # * `marker` A {Marker} you want this decoration to follow. - # * `decorationParams` An {Object} representing the decoration - # * `class` This CSS class will be applied to the decorated line number. - # * `onlyHead` (optional) If `true`, the decoration will only be applied to - # the head of the marker. - # * `onlyEmpty` (optional) If `true`, the decoration will only be applied if - # the associated marker is empty. - # * `onlyNonEmpty` (optional) If `true`, the decoration will only be applied - # if the associated marker is non-empty. + # * `decorationParams` An {Object} representing the decoration. It is passed + # to {TextEditor::decorateMarker} as its `decorationParams` and so supports + # all options documented there. + # * `type` __Caveat__: set to `'line-number'` if this is the line-number + # gutter, `'gutter'` otherwise. This cannot be overridden. # # Returns a {Decoration} object decorateMarker: (marker, options) -> diff --git a/src/text-editor.coffee b/src/text-editor.coffee index 8dce16439..62cd167b9 100644 --- a/src/text-editor.coffee +++ b/src/text-editor.coffee @@ -1253,7 +1253,7 @@ class TextEditor extends Model # is invalidated, or is destroyed, the decoration will be updated to reflect # the marker's state. # - # There are three types of supported decorations: + # The following are the supported decorations types: # # * __line__: Adds your CSS `class` to the line nodes within the range # marked by the marker @@ -1269,36 +1269,46 @@ class TextEditor extends Model #
# # ``` + # * __overlay__: Positions the view associated with the given item at the head + # or tail of the given `Marker`. + # * __gutter__: A decoration that tracks a {Marker} in a {Gutter}. Gutter + # decorations are created by calling {Gutter::decorateMarker} on the + # desired `Gutter` instance. # # ## Arguments # # * `marker` A {Marker} you want this decoration to follow. # * `decorationParams` An {Object} representing the decoration e.g. # `{type: 'line-number', class: 'linter-error'}` - # * `type` There are a few supported decoration types: `line-number`, `line`, - # `highlight`, and `overlay`. The behavior of the types are as follows: - # * `line-number` Adds the given `class` to the line numbers overlapping the - # rows spanned by the marker. + # * `type` There are several supported decoration types. The behavior of the + # types are as follows: # * `line` Adds the given `class` to the lines overlapping the rows - # spanned by the marker. + # spanned by the `Marker`. + # * `line-number` Adds the given `class` to the line numbers overlapping + # the rows spanned by the `Marker`. # * `highlight` Creates a `.highlight` div with the nested class with up - # to 3 nested regions that fill the area spanned by the marker. + # to 3 nested regions that fill the area spanned by the `Marker`. # * `overlay` Positions the view associated with the given item at the - # head or tail of the given marker, depending on the `position` + # head or tail of the given `Marker`, depending on the `position` # property. + # * `gutter` Tracks a {Marker} in a {Gutter}. Created by calling + # {Gutter::decorateMarker} on the desired `Gutter` instance. # * `class` This CSS class will be applied to the decorated line number, # line, highlight, or overlay. + # * `item` (optional) An {HTMLElement} or a model {Object} with a + # corresponding view registered. Only applicable to the `gutter` and + # `overlay` types. # * `onlyHead` (optional) If `true`, the decoration will only be applied to - # the head of the marker. Only applicable to the `line` and `line-number` - # types. - # * `onlyEmpty` (optional) If `true`, the decoration will only be applied if - # the associated marker is empty. Only applicable to the `line` and + # the head of the `Marker`. Only applicable to the `line` and # `line-number` types. + # * `onlyEmpty` (optional) If `true`, the decoration will only be applied if + # the associated `Marker` is empty. Only applicable to the `gutter`, + # `line`, and `line-number` types. # * `onlyNonEmpty` (optional) If `true`, the decoration will only be applied - # if the associated marker is non-empty. Only applicable to the `line` - # and `line-number` types. + # if the associated `Marker` is non-empty. Only applicable to the + # `gutter`, `line`, and `line-number` types. # * `position` (optional) Only applicable to decorations of type `overlay`, - # controls where the overlay view is positioned relative to the marker. + # controls where the overlay view is positioned relative to the `Marker`. # Values can be `'head'` (the default), or `'tail'`. # # Returns a {Decoration} object