Update: JSDoc documentation for notification system (fixes #810) #811
+760
−40
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Added detailed JSDoc documentation to notification-related files, including models, collections, views, and the main notification service. The comments describe module responsibilities, public APIs, integration points, known issues, and usage examples, improving code maintainability and developer onboarding.
oliverfoster
reviewed
Jan 6, 2026
Comment on lines
89
to
95
| * @example | ||
| * const model = new NotifyModel({ | ||
| * body: 'Delayed message', | ||
| * _delay: 1000 | ||
| * }); | ||
| * collection.add(model); | ||
| */ |
Member
There was a problem hiding this comment.
The only handle to a NotifyPushCollection is at notify.notifyPushes, NotifyPushCollection would not be instantiated by a developer.
We would use notify.push(options) instead of notify.notifyPushes.add(model).
oliverfoster
requested changes
Jan 8, 2026
| initialize({ notify }) { | ||
| this.notify = notify; | ||
| _.bindAll(this, 'onShadowClicked', 'resetNotifySize', 'onKeyDown'); | ||
|
|
Member
There was a problem hiding this comment.
Unnecessary whitespace addition.
| * _showIcon: true | ||
| * }); | ||
| * | ||
| * Adapt.on('course:save', () => { |
Member
There was a problem hiding this comment.
Same issue with not detaching handlers. Please correct for all cases where Adapt.on is not followed by Adapt.off clearup.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Comprehensive JSDoc documentation review and enhancement of the notification system (6 files). This PR sets to begin an established style guide with clear, practical examples and identified known issues/improvements for future JSDocs.
Fix
Update
notify.js- Added complete module-level documentation with public API, integration points, known issues, and customization examplesnotifyView.js- Fixed @example block inread()method; documented all public methods with parameters and working code examplesnotifyPopupView.js- Added modal documentation and event handler detailsnotifyPushView.js- Documented push notification display behavior, positioning, and public methodsnotifyModel.js- Documented side effects, idempotency, and async API foronClosed()notifyPushCollection.js- Added queue management documentation with focus on side effectsDocumentation Standards Applied
What Gets Documented:
@param,@returns,@example@class,@classdesc,@module,@fileWhat Gets Skipped:
defaults(),className(),attributes(),tagName(),events()preRender(),postRender(),render(), etc. where name + code are self-explanatorythis._stack,this.hasOpened@listenstags (wiring is obvious from code)@eventtags (redundant with@fires)change,sync, etc.Testing
Verify all 6 files are valid JSDoc:
npm run build # Ensures JSDoc parsing succeedsCheck style guide compliance:
Validate documentation structure:
Test specific changes:
notify.js: Verify examples work with Adapt APInotifyView.js: Confirmread()method is properly documentednotifyPopupView.js: Check modal lifecycle documentationnotifyPushView.js: Verify positioning behavior is clearnotifyModel.js: Check async API is documentednotifyPushCollection.js: Confirm queue behavior is clearClarity Check: