Skip to content

Commit 34ab8de

Browse files
devvaannshabose
authored andcommitted
docs: refine API docs for files in Language dir
1 parent 4b202c8 commit 34ab8de

File tree

15 files changed

+380
-680
lines changed

15 files changed

+380
-680
lines changed

docs/API-Reference/language/CSSUtils.md

Lines changed: 64 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,6 @@ const CSSUtils = brackets.getModule("language/CSSUtils")
88
## CodeMirror
99
Set of utilities for simple parsing of CSS text.
1010

11-
**Kind**: global variable
12-
<a name="_bracketPairs"></a>
13-
14-
## \_bracketPairs : <code>Object</code>
15-
List of all bracket pairs that is keyed by opening brackets, and the inverted listthat is keyed by closing brackets.
16-
1711
**Kind**: global variable
1812
<a name="isCSSPreprocessorFile"></a>
1913

@@ -43,13 +37,16 @@ Returns a context info object for the given cursor position
4337
<a name="getInfoAtPos.._contextCM"></a>
4438

4539
### getInfoAtPos.\_contextCM
46-
We will use this CM to cook css context in case of style attribute valueas CM in htmlmixed mode doesn't yet identify this as css context. We providea no-op display function to run CM without a DOM head.
40+
We will use this CM to cook css context in case of style attribute value
41+
as CM in htmlmixed mode doesn't yet identify this as css context. We provide
42+
a no-op display function to run CM without a DOM head.
4743

4844
**Kind**: inner property of [<code>getInfoAtPos</code>](#getInfoAtPos)
4945
<a name="getCompleteSelectors"></a>
5046

5147
## getCompleteSelectors(info, [useGroup]) ⇒ <code>string</code>
52-
Return a string that shows the literal parent hierarchy of the selectorin info.
48+
Return a string that shows the literal parent hierarchy of the selector
49+
in info.
5350

5451
**Kind**: global function
5552
**Returns**: <code>string</code> - the literal parent hierarchy of the selector
@@ -62,29 +59,30 @@ Return a string that shows the literal parent hierarchy of the selectorin info.
6259
<a name="extractAllSelectors"></a>
6360

6461
## extractAllSelectors(text, documentMode) ⇒ [<code>Array.&lt;SelectorInfo&gt;</code>](#SelectorInfo)
65-
Extracts all CSS selectors from the given textReturns an array of SelectorInfo. Each SelectorInfo is an object with the following properties:
66-
selector: the text of the selector (note: comma separated selector groups like
67-
"h1, h2" are broken into separate selectors)
68-
ruleStartLine: line in the text where the rule (including preceding comment) appears
69-
ruleStartChar: column in the line where the rule (including preceding comment) starts
70-
selectorStartLine: line in the text where the selector appears
71-
selectorStartChar: column in the line where the selector starts
72-
selectorEndLine: line where the selector ends
73-
selectorEndChar: column where the selector ends
74-
selectorGroupStartLine: line where the comma-separated selector group (e.g. .foo, .bar, .baz)
75-
starts that this selector (e.g. .baz) is part of. Particularly relevant for
76-
groups that are on multiple lines.
77-
selectorGroupStartChar: column in line where the selector group starts.
78-
selectorGroup: the entire selector group containing this selector, or undefined if there
79-
is only one selector in the rule.
80-
declListStartLine: line where the declaration list for the rule starts
81-
declListStartChar: column in line where the declaration list for the rule starts
82-
declListEndLine: line where the declaration list for the rule ends
83-
declListEndChar: column in the line where the declaration list for the rule ends
84-
level: the level of the current selector including any containing @media block in the
85-
nesting level count. Use this property with caution since it is primarily for internal
86-
parsing use. For example, two sibling selectors may have different levels if one
87-
of them is nested inside an @media block and it should not be used for sibling info.
62+
Extracts all CSS selectors from the given text
63+
Returns an array of SelectorInfo. Each SelectorInfo is an object with the following properties:
64+
selector: the text of the selector (note: comma separated selector groups like
65+
"h1, h2" are broken into separate selectors)
66+
ruleStartLine: line in the text where the rule (including preceding comment) appears
67+
ruleStartChar: column in the line where the rule (including preceding comment) starts
68+
selectorStartLine: line in the text where the selector appears
69+
selectorStartChar: column in the line where the selector starts
70+
selectorEndLine: line where the selector ends
71+
selectorEndChar: column where the selector ends
72+
selectorGroupStartLine: line where the comma-separated selector group (e.g. .foo, .bar, .baz)
73+
starts that this selector (e.g. .baz) is part of. Particularly relevant for
74+
groups that are on multiple lines.
75+
selectorGroupStartChar: column in line where the selector group starts.
76+
selectorGroup: the entire selector group containing this selector, or undefined if there
77+
is only one selector in the rule.
78+
declListStartLine: line where the declaration list for the rule starts
79+
declListStartChar: column in line where the declaration list for the rule starts
80+
declListEndLine: line where the declaration list for the rule ends
81+
declListEndChar: column in the line where the declaration list for the rule ends
82+
level: the level of the current selector including any containing @media block in the
83+
nesting level count. Use this property with caution since it is primarily for internal
84+
parsing use. For example, two sibling selectors may have different levels if one
85+
of them is nested inside an @media block and it should not be used for sibling info.
8886
parentSelectors: all ancestor selectors separated with '/' if the current selector is a nested one
8987

9088
**Kind**: global function
@@ -95,75 +93,28 @@ Extracts all CSS selectors from the given textReturns an array of SelectorInfo.
9593
| text | <code>string</code> | CSS text to extract from |
9694
| documentMode | <code>string</code> | language mode of the document that text belongs to, default to css if undefined. |
9795

98-
<a name="_stripAtRules"></a>
99-
100-
## \_stripAtRules(selector) ⇒ <code>string</code>
101-
Helper function to remove whitespaces before and after a selectorReturns trimmed selector if it is not an at-rule, or null if it starts with @.
102-
103-
**Kind**: global function
104-
105-
| Param | Type |
106-
| --- | --- |
107-
| selector | <code>string</code> |
108-
109-
<a name="_getSelectorInFinalCSSForm"></a>
110-
111-
## \_getSelectorInFinalCSSForm(selectorArray) ⇒ <code>string</code>
112-
Converts the given selector array into the actual CSS selectors similar tothose generated by a CSS preprocessor.
113-
114-
**Kind**: global function
115-
116-
| Param | Type |
117-
| --- | --- |
118-
| selectorArray | <code>Array.&lt;string&gt;</code> |
119-
120-
<a name="_findAllMatchingSelectorsInText"></a>
121-
122-
## \_findAllMatchingSelectorsInText(text, selector, mode) ⇒ <code>Object</code>
123-
Finds all instances of the specified selector in "text".Returns an Array of Objects with start and end properties.For now, we only support simple selectors. This function will need to changedramatically to support full selectors.FUTURE: (JRB) It would be nice to eventually use the browser/jquery to do the selector evaluation.One way to do this would be to take the user's HTML, add a special attribute to every tag with a UID,and then construct a DOM (using the commented out code above). Then, give this DOM and the selector tojquery and ask what matches. If the node that the user's cursor is in comes back from jquery, thenwe know the selector applies.
124-
125-
**Kind**: global function
126-
**Returns**: <code>Object</code> - Array of objects containing the start and end line numbers (0-based, inclusive range) for each matched selector.
127-
128-
| Param | Type | Description |
129-
| --- | --- | --- |
130-
| text | <code>string</code> | CSS text to search |
131-
| selector | <code>string</code> | selector to search for |
132-
| mode | <code>string</code> | language mode of the document that text belongs to |
133-
134-
<a name="_addSelectorsToResults"></a>
135-
136-
## \_addSelectorsToResults(resultSelectors, selectorsToAdd, sourceDoc, lineOffset)
137-
Converts the results of _findAllMatchingSelectorsInText() into a simpler bag of data andappends those new objects to the given 'resultSelectors' Array.
138-
139-
**Kind**: global function
140-
141-
| Param | Type | Description |
142-
| --- | --- | --- |
143-
| resultSelectors | <code>Object</code> | Array |
144-
| selectorsToAdd | [<code>Array.&lt;SelectorInfo&gt;</code>](#SelectorInfo) | |
145-
| sourceDoc | <code>Document</code> | |
146-
| lineOffset | <code>number</code> | Amount to offset all line number info by. Used if the first line of the parsed CSS text is not the first line of the sourceDoc. |
147-
148-
<a name="_findMatchingRulesInCSSFiles"></a>
149-
150-
## \_findMatchingRulesInCSSFiles()
151-
Finds matching selectors in CSS files; adds them to 'resultSelectors'
152-
153-
**Kind**: global function
154-
<a name="_findMatchingRulesInStyleBlocks"></a>
155-
156-
## \_findMatchingRulesInStyleBlocks()
157-
Finds matching selectors in the 'style' block of a single HTML file; adds them to 'resultSelectors'
158-
159-
**Kind**: global function
16096
<a name="findMatchingRules"></a>
16197

16298
## findMatchingRules(selector, htmlDocument) ⇒ <code>$.Promise</code>
163-
Return all rules matching the specified selector.For now, we only look at the rightmost simple selector. For example, searching for ".foo" willmatch these rules: .foo {} div .foo {} div.foo {} div .foo[bar="42"] {} div .foo:hovered {} div .foo::first-childbut will *not* match these rules: .foobar {} .foo .bar {} div .foo .bar {} .foo.bar {}
164-
165-
**Kind**: global function
166-
**Returns**: <code>$.Promise</code> - that will be resolved with an Array of objects containing the source document, start line, and end line (0-based, inclusive range) for each matching declaration list. Does not addRef() the documents returned in the array.
99+
Return all rules matching the specified selector.
100+
For now, we only look at the rightmost simple selector. For example, searching for ".foo" will
101+
match these rules:
102+
.foo {}
103+
div .foo {}
104+
div.foo {}
105+
div .foo[bar="42"] {}
106+
div .foo:hovered {}
107+
div .foo::first-child
108+
but will *not* match these rules:
109+
.foobar {}
110+
.foo .bar {}
111+
div .foo .bar {}
112+
.foo.bar {}
113+
114+
**Kind**: global function
115+
**Returns**: <code>$.Promise</code> - that will be resolved with an Array of objects containing the
116+
source document, start line, and end line (0-based, inclusive range) for each matching declaration list.
117+
Does not addRef() the documents returned in the array.
167118

168119
| Param | Type | Description |
169120
| --- | --- | --- |
@@ -173,44 +124,24 @@ Return all rules matching the specified selector.For now, we only look at the r
173124
<a name="findSelectorAtDocumentPos"></a>
174125

175126
## findSelectorAtDocumentPos(editor, pos) ⇒ <code>string</code>
176-
Returns the selector(s) of the rule at the specified document pos, or "" if the position isis not within a style rule.
127+
Returns the selector(s) of the rule at the specified document pos, or "" if the position is
128+
is not within a style rule.
177129

178130
**Kind**: global function
179-
**Returns**: <code>string</code> - Selector(s) for the rule at the specified position, or "" if the position is not within a style rule. If the rule has multiple selectors, a comma-separated selector string is returned.
131+
**Returns**: <code>string</code> - Selector(s) for the rule at the specified position, or "" if the position
132+
is not within a style rule. If the rule has multiple selectors, a comma-separated
133+
selector string is returned.
180134

181135
| Param | Type | Description |
182136
| --- | --- | --- |
183137
| editor | <code>Editor</code> | Editor to search |
184138
| pos | <code>Object</code> | Position to search |
185139

186-
<a name="_removeComments"></a>
187-
188-
## \_removeComments(content) ⇒ <code>string</code>
189-
removes CSS comments from the content
190-
191-
**Kind**: global function
192-
**Returns**: <code>string</code> - reduced content
193-
194-
| Param | Type | Description |
195-
| --- | --- | --- |
196-
| content | <code>string</code> | to reduce |
197-
198-
<a name="_removeStrings"></a>
199-
200-
## \_removeStrings(content) ⇒ <code>string</code>
201-
removes strings from the content
202-
203-
**Kind**: global function
204-
**Returns**: <code>string</code> - reduced content
205-
206-
| Param | Type | Description |
207-
| --- | --- | --- |
208-
| content | <code>string</code> | to reduce |
209-
210140
<a name="reduceStyleSheetForRegExParsing"></a>
211141

212142
## reduceStyleSheetForRegExParsing(content) ⇒ <code>string</code>
213-
Reduces the style sheet by removing comments and stringsso that the content can be parsed using a regular expression
143+
Reduces the style sheet by removing comments and strings
144+
so that the content can be parsed using a regular expression
214145

215146
**Kind**: global function
216147
**Returns**: <code>string</code> - reduced content
@@ -222,7 +153,9 @@ Reduces the style sheet by removing comments and stringsso that the content can
222153
<a name="addRuleToDocument"></a>
223154

224155
## addRuleToDocument(doc, selector, useTabChar, indentUnit) ⇒ <code>Object</code>
225-
Adds a new rule to the end of the given document, and returns the range of the added ruleand the position of the cursor on the indented blank line within it. Note that the range willnot include all the inserted text (we insert extra newlines before and after the rule).
156+
Adds a new rule to the end of the given document, and returns the range of the added rule
157+
and the position of the cursor on the indented blank line within it. Note that the range will
158+
not include all the inserted text (we insert extra newlines before and after the rule).
226159

227160
**Kind**: global function
228161
**Returns**: <code>Object</code> - The range of the inserted rule and the location where the cursor should be placed.
@@ -237,13 +170,17 @@ Adds a new rule to the end of the given document, and returns the range of the a
237170
<a name="consolidateRules"></a>
238171

239172
## consolidateRules()
240-
In the given rule array (as returned by `findMatchingRules()`), if multiple rules in a rowrefer to the same rule (because there were multiple matching selectors), eliminate the redundantrules. Also, always use the selector group if available instead of the original matching selector.
173+
In the given rule array (as returned by `findMatchingRules()`), if multiple rules in a row
174+
refer to the same rule (because there were multiple matching selectors), eliminate the redundant
175+
rules. Also, always use the selector group if available instead of the original matching selector.
241176

242177
**Kind**: global function
243178
<a name="getRangeSelectors"></a>
244179

245180
## getRangeSelectors(range) ⇒ <code>string</code>
246-
Given a TextRange, extracts the selector(s) for the rule in the range and returns it.Assumes the range only contains one rule; if there's more than one, it will return theselector(s) for the first rule.
181+
Given a TextRange, extracts the selector(s) for the rule in the range and returns it.
182+
Assumes the range only contains one rule; if there's more than one, it will return the
183+
selector(s) for the first rule.
247184

248185
**Kind**: global function
249186
**Returns**: <code>string</code> - The selector(s) for the rule in the range.

0 commit comments

Comments
 (0)