Update: Add JSDoc documentation to content model hierarchy (fixes #852)

js/models/articleModel.js

@@ -1,7 +1,23 @@
+/**
+ * @file Article Model - Article data model
+ * @module core/js/models/articleModel
+ * @description Data model for article content. Extends
+ * {@link module:core/js/models/adaptModel~AdaptModel} to represent articles in the
+ * Adapt content hierarchy. Articles are children of content objects (pages) and
+ * parents of blocks. Registered as the 'article' component type.
+ */
+
 import components from 'core/js/components';
 import logging from 'core/js/logging';
 import AdaptModel from 'core/js/models/adaptModel';
 
+/**
+ * @class ArticleModel
+ * @classdesc Data model for an article. Articles are mid-level content containers
+ * in the Adapt hierarchy, sitting between content objects (pages) and blocks.
+ * Each article holds one or more blocks.
+ * @extends AdaptModel
+ */
 class ArticleModel extends AdaptModel {
 
   get _parent() {

js/models/blockModel.js

@@ -1,7 +1,23 @@
+/**
+ * @file Block Model - Block data model
+ * @module core/js/models/blockModel
+ * @description Data model for block content. Extends
+ * {@link module:core/js/models/adaptModel~AdaptModel} to represent blocks in the
+ * Adapt content hierarchy. Blocks are children of articles and parents of components.
+ * Registered as the 'block' component type.
+ */
+
 import components from 'core/js/components';
 import logging from 'core/js/logging';
 import AdaptModel from 'core/js/models/adaptModel';
 
+/**
+ * @class BlockModel
+ * @classdesc Data model for a block. Blocks are the direct containers of components
+ * in the Adapt hierarchy. Each block holds one or more components and sits within
+ * an article.
+ * @extends AdaptModel
+ */
 class BlockModel extends AdaptModel {
 
   get _parent() {

js/models/componentModel.js

@@ -1,8 +1,29 @@
+/**
+ * @file Component Model - Base component data model
+ * @module core/js/models/componentModel
+ * @description Base data model for all Adapt components. Extends
+ * {@link module:core/js/models/adaptModel~AdaptModel} to provide attempt tracking,
+ * user answer storage, and state restoration. Registered as the abstract 'component'
+ * type to support deprecated view-only components.
+ *
+ * Attempt state is stored as a compact array format `[numbers[], booleans[], arrays[]]`
+ * for efficient SCORM tracking. Use {@link module:core/js/models/componentModel~ComponentModel#getAttemptObject}
+ * to retrieve a readable key-value representation.
+ */
+
 import components from 'core/js/components';
 import Adapt from 'core/js/adapt';
 import logging from 'core/js/logging';
 import AdaptModel from 'core/js/models/adaptModel';
 
+/**
+ * @class ComponentModel
+ * @classdesc Base data model for Adapt components. Manages user answer storage,
+ * attempt state serialization, and state restoration for SCORM tracking. All
+ * interactive Adapt components extend this model. Component models are leaf nodes
+ * in the Adapt content hierarchy, held within blocks.
+ * @extends AdaptModel
+ */
 class ComponentModel extends AdaptModel {
 
   get _parent() {

js/models/contentObjectModel.js

@@ -1,7 +1,23 @@
+/**
+ * @file Content Object Model - Base model for pages and menus
+ * @module core/js/models/contentObjectModel
+ * @description Base data model for content objects (pages and menus). Extends
+ * {@link module:core/js/models/adaptModel~AdaptModel} to represent navigable course
+ * sections that are direct children of the course root or a nested menu.
+ */
+
 import Adapt from 'core/js/adapt';
 import logging from 'core/js/logging';
 import AdaptModel from 'core/js/models/adaptModel';
 
+/**
+ * @class ContentObjectModel
+ * @classdesc Base data model for content objects — pages and menus. Content objects are
+ * the navigable sections of a course, sitting directly below the course root or nested
+ * inside menus. Provides base type-group identification and deprecated navigation helpers
+ * for the content object hierarchy.
+ * @extends AdaptModel
+ */
 export default class ContentObjectModel extends AdaptModel {
 
   get _parent() {

js/models/courseModel.js

@@ -1,7 +1,22 @@
+/**
+ * @file Course Model - Top-level course data model
+ * @module core/js/models/courseModel
+ * @description Data model for the course root node. Extends {@link module:core/js/models/menuModel~MenuModel}
+ * to represent the top-level course container. Registered as the 'course' component type.
+ */
+
 import components from 'core/js/components';
 import logging from 'core/js/logging';
 import MenuModel from 'core/js/models/menuModel';
 
+/**
+ * @class CourseModel
+ * @classdesc Top-level course data model. Represents the root course node in the Adapt
+ * content hierarchy. The course is the parent of all content objects and has no parent
+ * of its own. Extends {@link module:core/js/models/menuModel~MenuModel} with course-specific
+ * type identification.
+ * @extends MenuModel
+ */
 class CourseModel extends MenuModel {
 
   get _parent() {

js/models/menuModel.js

@@ -1,7 +1,24 @@
+/**
+ * @file Menu Model - Menu content object data model
+ * @module core/js/models/menuModel
+ * @description Data model for menu content objects. Extends
+ * {@link module:core/js/models/contentObjectModel~ContentObjectModel} to represent
+ * menus that contain other content objects. Menus apply locking logic to their
+ * children via {@link module:core/js/models/menuModel~MenuModel#setCustomLocking}.
+ * Registered as the 'menu' component type.
+ */
+
 import components from 'core/js/components';
 import logging from 'core/js/logging';
 import ContentObjectModel from 'core/js/models/contentObjectModel';
 
+/**
+ * @class MenuModel
+ * @classdesc Data model for a menu content object. Menus are container nodes in the
+ * content object hierarchy that hold other content objects (pages or nested menus).
+ * Applies lock state to children based on the configured locking strategy.
+ * @extends ContentObjectModel
+ */
 class MenuModel extends ContentObjectModel {
 
   get _children() {
@@ -17,6 +34,10 @@ class MenuModel extends ContentObjectModel {
     return 'menu';
   }
 
+  /**
+   * Applies lock state to each available child model using the configured locking strategy.
+   * Recursively triggers locking on any child that is itself a {@link MenuModel}.
+   */
   setCustomLocking() {
     const children = this.getAvailableChildModels();
     children.forEach(child => {

js/models/pageModel.js

@@ -1,7 +1,23 @@
+/**
+ * @file Page Model - Page content object data model
+ * @module core/js/models/pageModel
+ * @description Data model for page content objects. Extends
+ * {@link module:core/js/models/contentObjectModel~ContentObjectModel} to represent
+ * learner-facing pages. Pages are leaf-level content objects that contain articles.
+ * Registered as the 'page' component type.
+ */
+
 import components from 'core/js/components';
 import logging from 'core/js/logging';
 import ContentObjectModel from 'core/js/models/contentObjectModel';
 
+/**
+ * @class PageModel
+ * @classdesc Data model for a page content object. Pages are the learner-facing navigable
+ * sections of a course that contain articles. They are leaf nodes in the content object
+ * hierarchy — unlike menus, pages do not contain other content objects.
+ * @extends ContentObjectModel
+ */
 class PageModel extends ContentObjectModel {
 
   get _children() {

js/mpabc.js

@@ -1,3 +1,16 @@
+/**
+ * @file MPABC - Menus, Pages, Articles, Blocks and Components controller
+ * @module core/js/mpabc
+ * @description Singleton controller that bootstraps the core Adapt content hierarchy.
+ * Registers the primary content type models and views (menus, pages, articles, blocks,
+ * components), then creates {@link AdaptSubsetCollection} instances on the `Adapt` global
+ * for each type: `Adapt.contentObjects`, `Adapt.articles`, `Adapt.blocks`, and
+ * `Adapt.components`. Coordinates data loading via the wait API.
+ *
+ * @example
+ * import 'core/js/mpabc'; // imported for side-effects; bootstraps the content hierarchy
+ */
+
 import Adapt from 'core/js/adapt';
 import wait from 'core/js/wait';
 import Data from 'core/js/data';
@@ -14,6 +27,15 @@ import 'core/js/views/pageView';
 import 'core/js/views/articleView';
 import 'core/js/views/blockView';
 
+/**
+ * @class MPABC
+ * @classdesc Singleton controller responsible for bootstrapping the core content type
+ * hierarchy. Sets up `Adapt.contentObjects`, `Adapt.articles`, `Adapt.blocks`, and
+ * `Adapt.components` as {@link AdaptSubsetCollection} instances filtered by model type.
+ * Coordinates with the data loader via the wait API to ensure collections are ready
+ * before the framework proceeds.
+ * @extends Backbone.Controller
+ */
 class MPABC extends Backbone.Controller {
 
   initialize() {