Documentation

Code Comments · Mini-Lesson Documentation · Code Highlights

📝 Code Comments

Every custom class and method in the game has JSDoc documentation with @class, @extends, @param, and @returns tags. Inline comments explain non-obvious logic throughout. Comment density exceeds the 10% requirement across all source files.

JSDoc class documentation — PeppaBossEnemy

/**
 * PeppaBossEnemy — custom boss class extending the Enemy base.
 * Adds health system, defeat state, invulnerability window,
 * movement AI, and hitbox debug visualization.
 *
 * @class PeppaBossEnemy
 * @extends Enemy
 * @example
 * // Instantiated automatically by the engine via this.classes array
 * const boss = new PeppaBossEnemy(sprite_data_enemy, gameEnv);
 */
class PeppaBossEnemy extends Enemy {

  /**
   * @param {Object} data              - Sprite and config data
   * @param {number} data.health       - Starting HP for this boss
   * @param {number} data.moveSpeed    - Pixels per frame toward player
   * @param {Object} gameEnv           - Shared game environment reference
   */
  constructor(data = null, gameEnv = null) {
    super(data, gameEnv);
    /** @type {number} Current health points */
    this.health = data?.health ?? 3;
    /** @type {boolean} Whether boss is currently in defeat state */
    this.isDefeated = false;
    /** @type {boolean} Whether boss can currently receive damage */
    this.isVulnerable = true;
  }
}

JSDoc method documentation — takeDamage()

/**
 * Applies damage to the boss. Respects invulnerability window and defeat state.
 * Starts the 300ms invulnerability cooldown after each successful hit.
 *
 * @param {number} amount - HP to subtract (default 1)
 * @returns {boolean} true if this hit caused defeat, false otherwise
 */
takeDamage(amount = 1) {
  if (this.isDefeated) return true;
  if (!this.isVulnerable) return false;
  this.health = Math.max(0, this.health - amount);
  this.isVulnerable = false;
  this.lastDamagedAt = Date.now();
  if (this.health === 0) this.isDefeated = true;
  return this.isDefeated;
}

/**
 * Moves boss toward a target object each frame using normalized direction.
 * @param {Object} target - game object with .position, .width, .height
 * @returns {boolean} true if movement occurred, false if already at target
 */
moveTowardPlayer(target) {
  const dx = (target.position.x + target.width  / 2) - (this.position.x + this.width  / 2);
  const dy = (target.position.y + target.height / 2) - (this.position.y + this.height / 2);
  const distance = Math.hypot(dx, dy);
  if (distance > 1) {
    this.position.x += (dx / distance) * this.moveSpeed;
    this.position.y += (dy / distance) * this.moveSpeed;
    return true;
  }
  return false;
}

Strategic inline comment pattern

// Strategic console.log placement — prefixed tags make logs easy to filter
console.log(`[PeppaBossEnemy] Spawned: ${data?.id} with ${this.health} HP`);
console.log(`[Boss] Hit! HP: ${this.health}/${this.maxHealth}`);
console.log(`[Boss] Invulnerable, ignoring damage.`);
console.log(`[Boss] Defeated!`);
console.log(`[Hitbox] pos=(${Math.round(this.position.x)},${Math.round(this.position.y)})`);
console.log(`[Leaderboard] Score saved:`, data);
console.error(`[Leaderboard] POST failed:`, error.message);

📖 Mini-Lesson Documentation

The rubric requires a comic/visual post with embedded runtime game demo in the personal portfolio. This entire blog — eight separate pages with annotated code snippets, concept explanations, live code runners, and a playable embedded game — is that mini-lesson.

What each page teaches

The game itself is the runtime demo referenced throughout every page.

✨ Code Highlights

The rubric requires annotated key code snippets demonstrating OOP, APIs, and collision. Every page in this blog uses the same annotation pattern — a blue left-border callout box under each code block that explains WHY the code is written the way it is, not just what it does.

Annotation pattern — used on every page

Key annotated snippets across the blog

▶ Documentation Practice

Run the code below to see documented classes in action. The JSDoc comments describe each method — try adding your own @param comments or a new documented method.