8000 Improve JSDoc comments. (#477) · js-data/js-data@c3d102a · GitHub
[go: up one dir, main page]
Skip to content

Commit c3d102a

Browse files
jmdobryjmdobry
authored
Improve JSDoc comments. (#477)
1 parent 12c14d3 commit c3d102a

14 files changed

+1983
-1933
lines changed

‎src/Collection.js

Lines changed: 91 additions & 98 deletions
Large diffs are not rendered by default.

‎src/Component.js

Lines changed: 58 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import Settable from './Settable'
1616
* ```
1717
*
1818
* @class Component
19-
* @param {Object} [opts] Configuration options.
19+
* @param {object} [opts] Configuration options.
2020
* @param {boolean} [opts.debug=false] See {@link Component#debug}.
2121
* @returns {Component} A new {@link Component} instance.
2222
* @since 3.0.0
@@ -31,16 +31,15 @@ function Component (opts) {
3131
* functionality.
3232
*
3333
* @example <caption>Component#debug</caption>
34-
* // Normally you would do: import {Component} from 'js-data'
35-
* const JSData = require('js-data@3.0.0-rc.4')
36-
* const {Component} = JSData
37-
* console.log('Using JSData v' + JSData.version.full)
34+
* const JSData = require('js-data');
35+
* const { Component } = JSData;
36+
* console.log('Using JSData v' + JSData.version.full);
3837
*
39-
* const component = new Component()
40-
* component.log('debug', 'some message') // nothing gets logged
38+
* const component = new Component();
39+
* component.log('debug', 'some message'); // nothing gets logged
4140
* // Display debug logs:
42-
* component.debug = true
43-
* component.log('debug', 'other message') // this DOES get logged
41+
* component.debug = true;
42+
* component.log('debug', 'other message'); // this DOES get logged
4443
*
4544
* @default false
4645
* @name Component#debug
@@ -70,52 +69,51 @@ export default Settable.extend({
7069
* Create a subclass of this Component:
7170
*
7271
* @example <caption>Component.extend</caption>
73-
* // Normally you would do: import {Component} from 'js-data'
74-
* const JSData = require('js-data@3.0.0-rc.4')
75-
* const {Component} = JSData
76-
* console.log('Using JSData v' + JSData.version.full)
72+
* const JSData = require('js-data');
73+
* const { Component } = JSData;
74+
* console.log('Using JSData v' + JSData.version.full);
7775
*
7876
* // Extend the class using ES2015 class syntax.
7977
* class CustomComponentClass extends Component {
80-
* foo () { return 'bar' }
81-
* static beep () { return 'boop' }
78+
* foo () { return 'bar'; }
79+
* static beep () { return 'boop'; }
8280
* }
83-
* const customComponent = new CustomComponentClass()
84-
* console.log(customComponent.foo())
85-
* console.log(CustomComponentClass.beep())
81+
* const customComponent = new CustomComponentClass();
82+
* console.log(customComponent.foo());
83+
* console.log(CustomComponentClass.beep());
8684
*
8785
* // Extend the class using alternate method.
8886
* const OtherComponentClass = Component.extend({
89-
* foo () { return 'bar' }
87+
* foo () { return 'bar'; }
9088
* }, {
91-
* beep () { return 'boop' }
92-
* })
93-
* const otherComponent = new OtherComponentClass()
94-
* console.log(otherComponent.foo())
95-
* console.log(OtherComponentClass.beep())
89+
* beep () { return 'boop'; }
90+
* });
91+
* const otherComponent = new OtherComponentClass();
92+
* console.log(otherComponent.foo());
93+
* console.log(OtherComponentClass.beep());
9694
*
9795
* // Extend the class, providing a custom constructor.
9896
* function AnotherComponentClass () {
99-
* Component.call(this)
100-
* this.created_at = new Date().getTime()
97+
* Component.call(this);
98+
* this.created_at = new Date().getTime();
10199
* }
102100
* Component.extend({
103101
* constructor: AnotherComponentClass,
104-
* foo () { return 'bar' }
102+
* foo () { return 'bar'; }
105103
* }, {
106-
* beep () { return 'boop' }
104+
* beep () { return 'boop'; }
107105
* })
108-
* const anotherComponent = new AnotherComponentClass()
109-
* console.log(anotherComponent.created_at)
110-
* console.log(anotherComponent.foo())
111-
* console.log(AnotherComponentClass.beep())
106+
* const anotherComponent = new AnotherComponentClass();
107+
* console.log(anotherComponent.created_at);
108+
* console.log(anotherComponent.foo());
109+
* console.log(AnotherComponentClass.beep());
112110
*
113111
* @method Component.extend
114-
* @param {Object} [props={}] Properties to add to the prototype of the
112+
* @param {object} [props={}] Properties to add to the prototype of the
115113
* subclass.
116-
* @param {Object} [props.constructor] Provide a custom constructor function
114+
* @param {object} [props.constructor] Provide a custom constructor function
117115
* to be used as the subclass itself.
118-
* @param {Object} [classProps={}] Static properties to add to the subclass.
116+
* @param {object} [classProps={}] Static properties to add to the subclass.
119117
* @returns {Constructor} Subclass of this Component class.
120118
* @since 3.0.0
121119
*/
@@ -150,26 +148,26 @@ utils.logify(Component.prototype)
150148
* @example
151149
* // Listen for all "afterCreate" events in a DataStore
152150
* store.on('afterCreate', (mapperName, props, opts, result) => {
153-
* console.log(mapperName) // "post"
154-
* console.log(props.id) // undefined
155-
* console.log(result.id) // 1234
156-
* })
151+
* console.log(mapperName); // "post"
152+
* console.log(props.id); // undefined
153+
* console.log(result.id); // 1234
154+
* });
157155
* store.create('post', { title: 'Modeling your data' }).then((post) => {
158-
* console.log(post.id) // 1234
159-
* })
156+
* console.log(post.id); // 1234
157+
* });
160158
*
161159
* @example
162160
* // Listen for the "add" event on a collection
163161
* collection.on('add', (records) => {
164-
* console.log(records) // [...]
165-
* })
162+
* console.log(records); // [...]
163+
* });
166164
*
167165
* @example
168166
* // Listen for "change" events on a record
169167
* post.on('change', (record, changes) => {
170-
* console.log(changes) // { changed: { title: 'Modeling your data' } }
171-
* })
172-
* post.title = 'Modeling your data'
168+
* console.log(changes); // { changed: { title: 'Modeling your data' } }
169+
* });
170+
* post.title = 'Modeling your data';
173171
*
174172
* @method Component#on
175173
* @param {string} event Name of event to subsribe to.
@@ -184,15 +182,15 @@ utils.logify(Component.prototype)
184182
*
185183
* @example
186184
* // Remove a particular listener for a particular event
187-
* collection.off('add', handler)
185+
* collection.off('add', handler);
188186
*
189187
* @example
190188
* // Remove all listeners for a particular event
191-
* record.off('change')
189+
* record.off('change');
192190
*
193191
* @example
194192
* // Remove all listeners to all events
195-
* store.off()
193+
* store.off();
196194
*
197195
* @method Component#off
198196
* @param {string} [event] Name of event to unsubsribe to.
@@ -203,21 +201,21 @@ utils.logify(Component.prototype)
203201
* Trigger an event on this Component.
204202
*
205203
* @example <caption>Component#emit</caption>
206-
* // import {Collection, DataStore} from 'js-data'
207-
* const JSData = require('js-data@3.0.0-rc.4')
208-
* const {Collection, DataStore} = JSData
204+
* // import { Collection, DataStore } from 'js-data';
205+
* const JSData = require('js-data');
206+
* const { Collection, DataStore } = JSData;
209207
*
210-
* const collection = new Collection()
208+
* const collection = new Collection();
211209
* collection.on('foo', function (msg) {
212-
* console.log(msg)
213-
* })
214-
* collection.emit('foo', 'bar')
210+
* console.log(msg);
211+
* });
212+
* collection.emit('foo', 'bar');
215213
*
216-
* const store = new DataStore()
214+
* const store = new DataStore();
217215
* store.on('beep', function (msg) {
218-
* console.log(msg)
219-
* })
220-
* store.emit('beep', 'boop')
216+
* console.log(msg);
217+
* });
218+
* store.emit('beep', 'boop');
221219
*
222220
* @method Component#emit
223221
* @param {string} event Name of event to emit.

0 commit comments

Comments
 (0)
0