Update: JSDoc documentation for notification system (fixes #810)

[joe-replin]

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

• Fixes JSDocs - Core Notification System #810

Update

• notify.js - Added complete module-level documentation with public API, integration points, known issues, and customization examples
• notifyView.js - Fixed @example block in read() method; documented all public methods with parameters and working code examples
• notifyPopupView.js - Added modal documentation and event handler details
• notifyPushView.js - Documented push notification display behavior, positioning, and public methods
• notifyModel.js - Documented side effects, idempotency, and async API for onClosed()
• notifyPushCollection.js - Added queue management documentation with focus on side effects

Documentation Standards Applied

What Gets Documented:

• Functions and methods - With @param, @returns, @example
• Classes and modules - With @class, @classdesc, @module, @file
• Singletons - As services with clear APIs
• File-level descriptions - Purpose, responsibility, integration points
• Public APIs - Everything plugins can safely use
• Complex algorithms - With explanatory comments and examples

What Gets Skipped:

• Configuration methods - defaults(), className(), attributes(), tagName(), events()
• Obvious helper methods - preRender(), postRender(), render(), etc. where name + code are self-explanatory
• Variables and constants - Simple assignments, magic numbers
• Private properties - Internal state like this._stack, this.hasOpened
• Enums - Individual enum values (document the file, not each constant)
• Event listeners - No @listens tags (wiring is obvious from code)
• Event definitions - No @event tags (redundant with @fires)
• Internal/private events - Only document public API events
• Framework events - Backbone's change, sync, etc.
• Implementation details - How it works internally (use inline comments instead)
• Abstract "extension points" - Don't list WHAT can be customized; show HOW in examples

Testing

1. Verify all 6 files are valid JSDoc:

   npm run build  # Ensures JSDoc parsing succeeds

2. Check style guide compliance:

   • Verify all code examples contain executable code
   • Check that framework methods are not over-documented

3. Validate documentation structure:

   • Open each notify file and confirm:
     • File-level documentation is present
     • "Known Issues & Improvements" section exists
     • All public methods are documented with working examples
     • Private methods are marked as private
     • Public events are documented

4. Test specific changes:

   • notify.js: Verify examples work with Adapt API
   • notifyView.js: Confirm read() method is properly documented
   • notifyPopupView.js: Check modal lifecycle documentation
   • notifyPushView.js: Verify positioning behavior is clear
   • notifyModel.js: Check async API is documented
   • notifyPushCollection.js: Confirm queue behavior is clear

5. Clarity Check:

   • Review documentation for clarity and completeness
   • Verify code examples are clear and work as intended
   • Confirm integration points are easy to understand

[oliverfoster]

Lovely

[oliverfoster]

Can you remove the "Improvements" and "Known Issues" sections, please? We can do those as separate issues after a further analysis phase.

[oliverfoster]

🎉 This PR is included in version 6.76.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀