Fix doc comments: use /// and remove blank lines before class defs

examples/bank/src/account.bt

@@ -1,19 +1,18 @@
 // Copyright 2026 James Casey
 // SPDX-License-Identifier: Apache-2.0
 
-// Account actor — an independent process managing a single bank balance
-//
-// Each Account is a BEAM process. Deposits and withdrawals are message sends,
-// making them inherently serialised per-account. Overdraft protection raises
-// a structured error via `self error:`
-//
-// Usage:
-//   acct := Account spawn
-//   acct deposit: 500
-//   acct balance          // => 500
-//   acct withdraw: 200    // => 300
-//   acct withdraw: 9999   // => ERROR: Insufficient funds
-
+/// Account actor — an independent process managing a single bank balance
+///
+/// Each Account is a BEAM process. Deposits and withdrawals are message sends,
+/// making them inherently serialised per-account. Overdraft protection raises
+/// a structured error via `self error:`
+///
+/// Usage:
+///   acct := Account spawn
+///   acct deposit: 500
+///   acct balance          // => 500
+///   acct withdraw: 200    // => 300
+///   acct withdraw: 9999   // => ERROR: Insufficient funds
 Actor subclass: Account
   state: balance = 0
   state: owner = ""

examples/bank/src/bank.bt

@@ -1,18 +1,17 @@
 // Copyright 2026 James Casey
 // SPDX-License-Identifier: Apache-2.0
 
-// Bank actor — a registry and factory for Account actors
-//
-// The Bank maintains a Dictionary mapping account names to Account actor
-// references. Opening an account spawns a new Account process and registers
-// it. Looking up an account returns the live actor reference
-//
-// Usage:
-//   bank := Bank spawn
-//   bank openAccount: "Alice"
-//   alice := bank accountFor: "Alice"
-//   alice deposit: 1000
-
+/// Bank actor — a registry and factory for Account actors
+///
+/// The Bank maintains a Dictionary mapping account names to Account actor
+/// references. Opening an account spawns a new Account process and registers
+/// it. Looking up an account returns the live actor reference
+///
+/// Usage:
+///   bank := Bank spawn
+///   bank openAccount: "Alice"
+///   alice := bank accountFor: "Alice"
+///   alice deposit: 1000
 Actor subclass: Bank
   state: accounts = #{}
   state: lastCreated = nil

examples/bank/src/transaction.bt

@@ -1,16 +1,15 @@
 // Copyright 2026 James Casey
 // SPDX-License-Identifier: Apache-2.0
 
-// Transaction — an immutable value recording a transfer
-//
-// Transactions are value objects (Object subclass), not actors. They capture
-// the details of a transfer as an immutable record
-//
-// Usage:
-//   txn := Transaction new: #{#amount => 250, #from => "Alice", #to => "Bob", #status => "completed"}
-//   txn getAmount   // => 250
-//   txn getStatus   // => "completed"
-
+/// Transaction — an immutable value recording a transfer
+///
+/// Transactions are value objects (Object subclass), not actors. They capture
+/// the details of a transfer as an immutable record
+///
+/// Usage:
+///   txn := Transaction new: #{#amount => 250, #from => "Alice", #to => "Bob", #status => "completed"}
+///   txn getAmount   // => 250
+///   txn getStatus   // => "completed"
 Object subclass: Transaction
   state: amount = 0
   state: from = ""

examples/bank/src/transfer_agent.bt

@@ -1,20 +1,19 @@
 // Copyright 2026 James Casey
 // SPDX-License-Identifier: Apache-2.0
 
-// TransferAgent actor — coordinates transfers between two Account actors
-//
-// A TransferAgent moves money between accounts by sending withdraw and
-// deposit messages synchronously. Each Account handles its own validation
-// (e.g. overdraft protection) independently
-//
-// This demonstrates the actor coordination pattern: the TransferAgent
-// orchestrates two independent actors, and each actor enforces its own
-// invariants
-//
-// Usage:
-//   agent := TransferAgent spawn
-//   agent transfer: 250 from: alice to: bob
-
+/// TransferAgent actor — coordinates transfers between two Account actors
+///
+/// A TransferAgent moves money between accounts by sending withdraw and
+/// deposit messages synchronously. Each Account handles its own validation
+/// (e.g. overdraft protection) independently
+///
+/// This demonstrates the actor coordination pattern: the TransferAgent
+/// orchestrates two independent actors, and each actor enforces its own
+/// invariants
+///
+/// Usage:
+///   agent := TransferAgent spawn
+///   agent transfer: 250 from: alice to: bob
 Actor subclass: TransferAgent
   state: lastAmount = 0
 

examples/bank/src/typed_account.bt

@@ -1,13 +1,12 @@
 // Copyright 2026 James Casey
 // SPDX-License-Identifier: Apache-2.0
 
-// TypedAccount — typed variant of the Account actor
-//
-// Demonstrates ADR 0025 syntax:
-// - typed class modifier
-// - typed state fields
-// - typed parameters and return annotations
-
+/// TypedAccount — typed variant of the Account actor
+///
+/// Demonstrates ADR 0025 syntax:
+/// - typed class modifier
+/// - typed state fields
+/// - typed parameters and return annotations
 typed Actor subclass: TypedAccount
   state: balance: Integer = 0
   state: owner: String = ""

examples/chat-room/src/chat_member.bt

@@ -1,28 +1,27 @@
 // Copyright 2026 James Casey
 // SPDX-License-Identifier: Apache-2.0
 
-// Chat Member Actor — Part of Chat Room Demo (BT-431, BT-568)
-//
-// ChatMember represents a chat participant with a name, inbox, and room ref
-// It demonstrates:
-// - Actor-to-actor references (room field)
-// - Receiving formatted messages from other actors
-// - State mutations (name, inbox, room)
-//
-// Try it in the REPL:
-//   $ beamtalk repl
-//   > :load examples/chat-room/message.bt
-//   > :load examples/chat-room/chat_room.bt
-//   > :load examples/chat-room/chat_member.bt
-//   > room := ChatRoom spawn
-//   > alice := ChatMember spawn
-//   > alice setName: "Alice"
-//   > alice setRoom: room
-//   > room join: alice
-//   > room say: "Hello!" from: "Alice"
-//
-// See examples/chat-room/README.md for a full walkthrough
-
+/// Chat Member Actor — Part of Chat Room Demo (BT-431, BT-568)
+///
+/// ChatMember represents a chat participant with a name, inbox, and room ref
+/// It demonstrates:
+/// - Actor-to-actor references (room field)
+/// - Receiving formatted messages from other actors
+/// - State mutations (name, inbox, room)
+///
+/// Try it in the REPL:
+///   $ beamtalk repl
+///   > :load examples/chat-room/message.bt
+///   > :load examples/chat-room/chat_room.bt
+///   > :load examples/chat-room/chat_member.bt
+///   > room := ChatRoom spawn
+///   > alice := ChatMember spawn
+///   > alice setName: "Alice"
+///   > alice setRoom: room
+///   > room join: alice
+///   > room say: "Hello!" from: "Alice"
+///
+/// See examples/chat-room/README.md for a full walkthrough
 Actor subclass: ChatMember
   state: name = "Guest"        // Member's display name
   state: inbox = #()           // List of received messages

examples/chat-room/src/chat_room.bt

@@ -30,14 +30,12 @@
 // ===========================================================================
 // CHATROOM ACTOR
 // ===========================================================================
-//
-// ChatRoom manages a Set of member actors and a List of message strings
-// It demonstrates:
-// - Storing actor references (PIDs) in a Set
-// - String concatenation for formatted messages
-// - Broadcasting via do: iteration over actor Set
-// - List concatenation for message history
-
+/// ChatRoom manages a Set of member actors and a List of message strings
+/// It demonstrates:
+/// - Storing actor references (PIDs) in a Set
+/// - String concatenation for formatted messages
+/// - Broadcasting via do: iteration over actor Set
+/// - List concatenation for message history
 Actor subclass: ChatRoom
   state: members = Set new     // Set of ChatMember actor references
   state: history = #()         // List of formatted message strings

examples/chat-room/src/message.bt

@@ -1,21 +1,20 @@
 // Copyright 2026 James Casey
 // SPDX-License-Identifier: Apache-2.0
 
-// Message — Value type for chat messages (BT-568)
-//
-// Demonstrates:
-// 1. **Value types** — Object subclass (not Actor), no process overhead
-// 2. **State** — text and sender fields with defaults
-// 3. **Immutability** — value types are immutable Erlang maps
-// 4. **new: initialization** — creating instances with field values
-//
-// Usage in REPL:
-//   > :load examples/chat-room/message.bt
-//   > args := #{#text => "Hello!", #sender => "Alice"}
-//   > msg := Message new: args
-//   > msg getText
-//   > msg describe
-
+/// Message — Value type for chat messages (BT-568)
+///
+/// Demonstrates:
+/// 1. **Value types** — Object subclass (not Actor), no process overhead
+/// 2. **State** — text and sender fields with defaults
+/// 3. **Immutability** — value types are immutable Erlang maps
+/// 4. **new: initialization** — creating instances with field values
+///
+/// Usage in REPL:
+///   > :load examples/chat-room/message.bt
+///   > args := #{#text => "Hello!", #sender => "Alice"}
+///   > msg := Message new: args
+///   > msg getText
+///   > msg describe
 Object subclass: Message
   state: text = ""
   state: sender = "Anonymous"

examples/chat-room/src/moderator.bt

@@ -1,25 +1,24 @@
 // Copyright 2026 James Casey
 // SPDX-License-Identifier: Apache-2.0
 
-// Moderator — Actor subclass of ChatMember (BT-568)
-//
-// Demonstrates:
-// 1. **Actor inheritance** — ChatMember subclass: Moderator
-// 2. **super calls** — Moderator overrides say: to add "[MOD]" prefix
-// 3. **New methods** — kick: and mute: for moderation actions
-//
-// Usage in REPL:
-//   > :load examples/chat-room/message.bt
-//   > :load examples/chat-room/chat_room.bt
-//   > :load examples/chat-room/chat_member.bt
-//   > :load examples/chat-room/moderator.bt
-//   > room := ChatRoom spawn
-//   > mod := Moderator spawn
-//   > mod setName: "Admin"
-//   > mod setRoom: room
-//   > room join: mod
-//   > mod say: "Welcome!"
-
+/// Moderator — Actor subclass of ChatMember (BT-568)
+///
+/// Demonstrates:
+/// 1. **Actor inheritance** — ChatMember subclass: Moderator
+/// 2. **super calls** — Moderator overrides say: to add "[MOD]" prefix
+/// 3. **New methods** — kick: and mute: for moderation actions
+///
+/// Usage in REPL:
+///   > :load examples/chat-room/message.bt
+///   > :load examples/chat-room/chat_room.bt
+///   > :load examples/chat-room/chat_member.bt
+///   > :load examples/chat-room/moderator.bt
+///   > room := ChatRoom spawn
+///   > mod := Moderator spawn
+///   > mod setName: "Admin"
+///   > mod setRoom: room
+///   > room join: mod
+///   > mod say: "Welcome!"
 ChatMember subclass: Moderator
   state: muted = Set new        // Set of muted member names
 

examples/getting-started/src/counter.bt

@@ -1,23 +1,22 @@
 // Copyright 2026 James Casey
 // SPDX-License-Identifier: Apache-2.0
 
-// Counter actor class example
-// A simple stateful actor that can increment, decrement, and return its value
-//
-// Try it in the REPL:
-//   $ beamtalk repl
-//   > :load examples/counter.bt
-//   > c := Counter spawn
-//   > c increment
-//   > c increment
-//   > c getValue
-//   2
-//   > c decrement
-//   > c getValue
-//   1
-//
-// See examples/repl-tutorial.md for a full beginner's guide
-
+/// Counter actor class example
+/// A simple stateful actor that can increment, decrement, and return its value
+///
+/// Try it in the REPL:
+///   $ beamtalk repl
+///   > :load examples/counter.bt
+///   > c := Counter spawn
+///   > c increment
+///   > c increment
+///   > c getValue
+///   2
+///   > c decrement
+///   > c getValue
+///   1
+///
+/// See examples/repl-tutorial.md for a full beginner's guide
 Actor subclass: Counter
   state: value = 0
 

examples/getting-started/src/hanoi.bt

@@ -1,23 +1,22 @@
 // Copyright 2026 James Casey
 // SPDX-License-Identifier: Apache-2.0
 
-// Towers of Hanoi
-// A classic recursive algorithm that moves n disks between three pegs
-//
-// Try it in the REPL:
-//   $ beamtalk repl
-//   > :load examples/hanoi.bt
-//   > h := Hanoi new
-//   > h solve: 3 from: "A" to: "C" via: "B"
-//   Move disk from A to C
-//   Move disk from A to B
-//   Move disk from C to B
-//   Move disk from A to C
-//   Move disk from B to A
-//   Move disk from B to C
-//   Move disk from A to C
-//   nil
-
+/// Towers of Hanoi
+/// A classic recursive algorithm that moves n disks between three pegs
+///
+/// Try it in the REPL:
+///   $ beamtalk repl
+///   > :load examples/hanoi.bt
+///   > h := Hanoi new
+///   > h solve: 3 from: "A" to: "C" via: "B"
+///   Move disk from A to C
+///   Move disk from A to B
+///   Move disk from C to B
+///   Move disk from A to C
+///   Move disk from B to A
+///   Move disk from B to C
+///   Move disk from A to C
+///   nil
 Object subclass: Hanoi
 
   solve: n from: source to: target via: auxiliary =>

examples/getting-started/src/hello.bt

@@ -1,15 +1,14 @@
 // Copyright 2026 James Casey
 // SPDX-License-Identifier: Apache-2.0
 
-// Simple hello world example
-//
-// Try it in the REPL:
-//   $ beamtalk repl
-//   > :load examples/hello.bt
-//   Loaded Hello
-//   > Hello new
-//   {__class__: Hello}
-
+/// Simple hello world example
+///
+/// Try it in the REPL:
+///   $ beamtalk repl
+///   > :load examples/hello.bt
+///   Loaded Hello
+///   > Hello new
+///   {__class__: Hello}
 Object subclass: Hello
 
   greeting => "Hello, World!"