Skip to content

Commit 1ab22ce

Browse files
devvaannshabose
devvaannsh
authored and
abose
committed
docs: add missing jsdoc
1 parent 94fd865 commit 1ab22ce

File tree

2 files changed

+228
-10
lines changed

2 files changed

+228
-10
lines changed

‎docs/API-Reference/editor/CodeHintManager.md‎

Lines changed: 223 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,240 @@
33
const CodeHintManager = brackets.getModule("editor/CodeHintManager")
44
```
55

6-
<a name="registerHintProvider"></a>
6+
<a name="module_CodeHintManager"></a>
77

8-
## registerHintProvider(provider, languageIds, priority)
8+
## CodeHintManager
9+
__CodeHintManager Overview:__
10+
11+
The CodeHintManager mediates the interaction between the editor and a
12+
collection of hint providers. If hints are requested explicitly by the
13+
user, then the providers registered for the current language are queried
14+
for their ability to provide hints in order of descending priority by
15+
way their hasHints methods. Character insertions may also constitute an
16+
implicit request for hints; consequently, providers for the current
17+
language are also queried on character insertion for both their ability to
18+
provide hints and also for the suitability of providing implicit hints
19+
in the given editor context.
20+
21+
Once a provider responds affirmatively to a request for hints, the
22+
manager begins a hinting session with that provider, begins to query
23+
that provider for hints by way of its getHints method, and opens the
24+
hint list window. The hint list is kept open for the duration of the
25+
current session. The manager maintains the session until either:
26+
27+
1. the provider gives a null response to a request for hints;
28+
2. a deferred response to getHints fails to resolve;
29+
3. the user explicitly dismisses the hint list window;
30+
4. the editor is closed or becomes inactive; or
31+
5. the editor undergoes a "complex" change, e.g., a multi-character
32+
insertion, deletion or navigation.
33+
34+
Single-character insertions, deletions or navigations may not
35+
invalidate the current session; in which case, each such change
36+
precipitates a successive call to getHints.
37+
38+
If the user selects a hint from the rendered hint list then the
39+
provider is responsible for inserting the hint into the editor context
40+
for the current session by way of its insertHint method. The provider
41+
may use the return value of insertHint to request that an additional
42+
explicit hint request be triggered, potentially beginning a new
43+
session.
44+
45+
46+
__CodeHintProvider Overview:__
47+
48+
A code hint provider should implement the following three functions:
49+
50+
- `CodeHintProvider.hasHints(editor, implicitChar)`
51+
- `CodeHintProvider.getHints(implicitChar)`
52+
- `CodeHintProvider.insertHint(hint)`
53+
54+
The behavior of these three functions is described in detail below.
55+
56+
__CodeHintProvider.hasHints(editor, implicitChar)__
57+
58+
The method by which a provider indicates intent to provide hints for a
59+
given editor. The manager calls this method both when hints are
60+
explicitly requested (via, e.g., Ctrl-Space) and when they may be
61+
implicitly requested as a result of character insertion in the editor.
62+
If the provider responds negatively then the manager may query other
63+
providers for hints. Otherwise, a new hinting session begins with this
64+
provider, during which the manager may repeatedly query the provider
65+
for hints via the getHints method. Note that no other providers will be
66+
queried until the hinting session ends.
67+
68+
The implicitChar parameter is used to determine whether the hinting
69+
request is explicit or implicit. If the string is null then hints were
70+
explicitly requested and the provider should reply based on whether it
71+
is possible to return hints for the given editor context. Otherwise,
72+
the string contains just the last character inserted into the editor's
73+
document and the request for hints is implicit. In this case, the
74+
provider should determine whether it is both possible and appropriate
75+
to show hints. Because implicit hints can be triggered by every
76+
character insertion, hasHints may be called frequently; consequently,
77+
the provider should endeavor to return a value as quickly as possible.
78+
79+
Because calls to hasHints imply that a hinting session is about to
80+
begin, a provider may wish to clean up cached data from previous
81+
sessions in this method. Similarly, if the provider returns true, it
82+
may wish to prepare to cache data suitable for the current session. In
83+
particular, it should keep a reference to the editor object so that it
84+
can access the editor in future calls to getHints and insertHints.
85+
86+
param {Editor} editor
87+
A non-null editor object for the active window.
88+
89+
param {string} implicitChar
90+
Either null, if the hinting request was explicit, or a single character
91+
that represents the last insertion and that indicates an implicit
92+
hinting request.
93+
94+
return {boolean}
95+
Determines whether the current provider is able to provide hints for
96+
the given editor context and, in case implicitChar is non- null,
97+
whether it is appropriate to do so.
98+
99+
100+
__CodeHintProvider.getHints(implicitChar)__
101+
102+
The method by which a provider provides hints for the editor context
103+
associated with the current session. The getHints method is called only
104+
if the provider asserted its willingness to provide hints in an earlier
105+
call to hasHints. The provider may return null or false, which indicates
106+
that the manager should end the current hinting session and close the hint
107+
list window; or true, which indicates that the manager should end the
108+
current hinting session but immediately attempt to begin a new hinting
109+
session by querying registered providers. Otherwise, the provider should
110+
return a response object that contains the following properties:
111+
112+
1. hints, a sorted array hints that the provider could later insert
113+
into the editor;
114+
2. match, a string that the manager may use to emphasize substrings of
115+
hints in the hint list (case-insensitive); and
116+
3. selectInitial, a boolean that indicates whether or not the
117+
first hint in the list should be selected by default.
118+
4. handleWideResults, a boolean (or undefined) that indicates whether
119+
to allow result string to stretch width of display.
120+
121+
If the array of
122+
hints is empty, then the manager will render an empty list, but the
123+
hinting session will remain open and the value of the selectInitial
124+
property is irrelevant.
125+
126+
Alternatively, the provider may return a jQuery.Deferred object
127+
that resolves with an object with the structure described above. In
128+
this case, the manager will initially render the hint list window with
129+
a throbber and will render the actual list once the deferred object
130+
resolves to a response object. If a hint list has already been rendered
131+
(from an earlier call to getHints), then the old list will continue
132+
to be displayed until the new deferred has resolved.
133+
134+
Both the manager and the provider can reject the deferred object. The
135+
manager will reject the deferred if the editor changes state (e.g., the
136+
user types a character) or if the hinting session ends (e.g., the user
137+
explicitly closes the hints by pressing escape). The provider can use
138+
this event to, e.g., abort an expensive computation. Consequently, the
139+
provider may assume that getHints will not be called again until the
140+
deferred object from the current call has resolved or been rejected. If
141+
the provider rejects the deferred, the manager will end the hinting
142+
session.
143+
144+
The getHints method may be called by the manager repeatedly during a
145+
hinting session. Providers may wish to cache information for efficiency
146+
that may be useful throughout these sessions. The same editor context
147+
will be used throughout a session, and will only change during the
148+
session as a result of single-character insertions, deletions and
149+
cursor navigations. The provider may assume that, throughout the
150+
lifetime of the session, the getHints method will be called exactly
151+
once for each such editor change. Consequently, the provider may also
152+
assume that the document will not be changed outside of the editor
153+
during a session.
154+
155+
param {string} implicitChar
156+
Either null, if the request to update the hint list was a result of
157+
navigation, or a single character that represents the last insertion.
158+
159+
return {jQuery.Deferred|{
160+
hints: Array.<string|jQueryObject>,
161+
match: string,
162+
selectInitial: boolean,
163+
handleWideResults: boolean}}
164+
165+
Null if the provider wishes to end the hinting session. Otherwise, a
166+
response object, possibly deferred, that provides 1. a sorted array
167+
hints that consists either of strings or jQuery objects; 2. a string
168+
match, possibly null, that is used by the manager to emphasize
169+
matching substrings when rendering the hint list; and 3. a boolean that
170+
indicates whether the first result, if one exists, should be selected
171+
by default in the hint list window. If match is non-null, then the
172+
hints should be strings.
173+
174+
If the match is null, the manager will not
175+
attempt to emphasize any parts of the hints when rendering the hint
176+
list; instead the provider may return strings or jQuery objects for
177+
which emphasis is self-contained. For example, the strings may contain
178+
substrings that wrapped in bold tags. In this way, the provider can
179+
choose to let the manager handle emphasis for the simple and common case
180+
of prefix matching, or can provide its own emphasis if it wishes to use
181+
a more sophisticated matching algorithm.
182+
183+
184+
__CodeHintProvider.insertHint(hint)__
185+
186+
The method by which a provider inserts a hint into the editor context
187+
associated with the current session. The provider may assume that the
188+
given hint was returned by the provider in some previous call in the
189+
current session to getHints, but not necessarily the most recent call.
190+
After the insertion has been performed, the current hinting session is
191+
closed. The provider should return a boolean value to indicate whether
192+
or not the end of the session should be immediately followed by a new
193+
explicit hinting request, which may result in a new hinting session
194+
being opened with some provider, but not necessarily the current one.
195+
196+
param {string} hint
197+
The hint to be inserted into the editor context for the current session.
198+
199+
return {boolean}
200+
Indicates whether the manager should follow hint insertion with an
201+
explicit hint request.
202+
203+
204+
__CodeHintProvider.insertHintOnTab__
205+
206+
type {?boolean} insertHintOnTab
207+
Indicates whether the CodeHintManager should request that the provider of
208+
the current session insert the currently selected hint on tab key events,
209+
or if instead a tab character should be inserted into the editor. If omitted,
210+
the fallback behavior is determined by the CodeHintManager. The default
211+
behavior is to insert a tab character, but this can be changed with the
212+
insertHintOnTab Preference.
213+
214+
215+
* [CodeHintManager](#module_CodeHintManager)
216+
* [.registerHintProvider(provider, languageIds, priority)](#module_CodeHintManager..registerHintProvider)
217+
* [.hasValidExclusion(exclusion, textAfterCursor)](#module_CodeHintManager..hasValidExclusion) ⇒ <code>boolean</code>
218+
* [.isOpen()](#module_CodeHintManager..isOpen) ⇒ <code>boolean</code>
219+
220+
<a name="module_CodeHintManager..registerHintProvider"></a>
221+
222+
### CodeHintManager.registerHintProvider(provider, languageIds, priority)
9223
The method by which a CodeHintProvider registers its willingness to
10224
providing hints for editors in a given language.
11225

12-
**Kind**: global function
226+
**Kind**: inner method of [<code>CodeHintManager</code>](#module_CodeHintManager)
13227

14228
| Param | Type | Description |
15229
| --- | --- | --- |
16230
| provider | <code>CodeHintProvider</code> | The hint provider to be registered, described below. |
17231
| languageIds | <code>Array.&lt;string&gt;</code> | The set of language ids for which the provider is capable of providing hints. If the special language id name "all" is included then the provider may be called for any language. |
18232
| priority | <code>number</code> | Used to break ties among hint providers for a particular language. Providers with a higher number will be asked for hints before those with a lower priority value. Defaults to zero. |
19233

20-
<a name="hasValidExclusion"></a>
234+
<a name="module_CodeHintManager..hasValidExclusion"></a>
21235

22-
## hasValidExclusion(exclusion, textAfterCursor) ⇒ <code>boolean</code>
236+
### CodeHintManager.hasValidExclusion(exclusion, textAfterCursor) ⇒ <code>boolean</code>
23237
Test whether the provider has an exclusion that is still the same as text after the cursor.
24238

25-
**Kind**: global function
239+
**Kind**: inner method of [<code>CodeHintManager</code>](#module_CodeHintManager)
26240
**Returns**: <code>boolean</code> - true if the exclusion is not null and is exactly the same as textAfterCursor,
27241
false otherwise.
28242

@@ -31,10 +245,10 @@ false otherwise.
31245
| exclusion | <code>string</code> | Text not to be overwritten when the provider inserts the selected hint. |
32246
| textAfterCursor | <code>string</code> | Text that is immediately after the cursor position. |
33247

34-
<a name="isOpen"></a>
248+
<a name="module_CodeHintManager..isOpen"></a>
35249

36-
## isOpen() ⇒ <code>boolean</code>
250+
### CodeHintManager.isOpen() ⇒ <code>boolean</code>
37251
Test if a hint popup is open.
38252

39-
**Kind**: global function
253+
**Kind**: inner method of [<code>CodeHintManager</code>](#module_CodeHintManager)
40254
**Returns**: <code>boolean</code> - - true if the hints are open, false otherwise.

‎src/editor/CodeHintManager.js‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121

2222
// @INCLUDE_IN_API_DOCS
2323

24-
/*
24+
/**
2525
* __CodeHintManager Overview:__
2626
*
2727
* The CodeHintManager mediates the interaction between the editor and a
@@ -226,7 +226,11 @@
226226
* the fallback behavior is determined by the CodeHintManager. The default
227227
* behavior is to insert a tab character, but this can be changed with the
228228
* insertHintOnTab Preference.
229+
*
230+
* @module CodeHintManager
229231
*/
232+
233+
230234
define(function (require, exports, module) {
231235

232236

0 commit comments

Comments
 (0)