@macroforge/mcp-server 0.1.23 → 0.1.25

package/docs/builtin-macros/default.md

@@ -1,13 +1,13 @@
 # Default
 
-*The `Default` macro generates a static `default()` factory method that creates instances with default field values.*
+*The `Default` macro generates a static `defaultValue()` factory method that creates instances with default field values. It works like Rust's `#[derive(Default)]` trait.*
 
 ## Basic Usage
 
 <MacroExample before={data.examples.basic.before} after={data.examples.basic.after} />
 
 ```typescript
-const config = Config.default();
+const config = Config.defaultValue();
 console.log(config.host);    // ""
 console.log(config.port);    // 0
 console.log(config.enabled); // false
@@ -15,34 +15,65 @@ console.log(config.enabled); // false
 
 ## Automatic Default Values
 
-The Default macro automatically determines default values based on field types:
+Like Rust's `Default` trait, the macro automatically determines default values for primitive types and common collections:
 
-- `string` → `""` (empty string)
+| `string` | `""` | `String::default()` 
 
-- `number` → `0`
+| `number` | `0` | `i32::default()` 
 
-- `boolean` → `false`
+| `boolean` | `false` | `bool::default()` 
 
-- `bigint` → `0n`
+| `bigint` | `0n` | `i64::default()` 
 
-- `Array<T>` or `T[]` → `[]` (empty array)
+| `T[]` / `Array<T>` | `[]` | `Vec::default()` 
 
-- `Map<K, V>` → `new Map()`
+| `Map<K, V>` | `new Map()` | `HashMap::default()` 
 
-- `Set<T>` → `new Set()`
+| `Set<T>` | `new Set()` | `HashSet::default()` 
 
-- `Date` → `new Date()`
+| `Date` | `new Date()` | — 
 
-- Custom types → `null as any`
+| `T | null` / `T | undefined` | `null` | `Option::default()` 
+
+| Custom types | **Error** | **Error** (needs `impl Default`)
+
+## Nullable Types (like Rust's Option)
+
+Just like Rust's `Option<T>` defaults to `None`, nullable TypeScript types automatically default to `null`:
+
+<MacroExample before={data.examples.nullable.before} after={data.examples.nullable.after} />
+
+```typescript
+const user = User.defaultValue();
+console.log(user.name);     // ""
+console.log(user.email);    // null (nullable type)
+console.log(user.age);      // 0
+console.log(user.metadata); // null (nullable type)
+```
+
+## Custom Types Require @default
+
+Just like Rust requires `impl Default` for custom types, Macroforge requires the `@default()` decorator on fields with non-primitive types:
+
+<MacroExample before={data.examples.customType.before} after={data.examples.customType.after} />
+
+<p class="text-red-500 text-sm mt-2">
+Without `@default` on custom type fields, the macro will emit an error:
+</p>
+
+```text
+// Error: @derive(Default) cannot determine default for non-primitive fields.
+// Add @default(value) to: settings, permissions
+```
 
 ## Custom Default Values
 
-Use the `@defaultValue()` decorator to specify custom default values for fields:
+Use the `@default()` decorator to specify custom default values for any field:
 
 <MacroExample before={data.examples.custom.before} after={data.examples.custom.after} />
 
 ```typescript
-const config = ServerConfig.default();
+const config = ServerConfig.defaultValue();
 console.log(config.host);      // "localhost"
 console.log(config.port);      // 8080
 console.log(config.enabled);   // true
@@ -51,12 +82,12 @@ console.log(config.logLevels); // ["info", "error"]
 
 ## Interface Support
 
-Default also works with interfaces. For interfaces, a namespace is generated with a `default_()` function (note the underscore to avoid conflicts with the reserved word):
+Default also works with interfaces. For interfaces, a namespace is generated with a `defaultValue()` function:
 
 <MacroExample before={data.examples.interface.before} after={data.examples.interface.after} />
 
 ```typescript
-const origin = Point.default_();
+const origin = Point.defaultValue();
 console.log(origin); // { x: 0, y: 0 }
 ```
 
@@ -67,7 +98,7 @@ Default works with enums. For enums, it returns the first variant as the default
 <MacroExample before={data.examples.enum.before} after={data.examples.enum.after} />
 
 ```typescript
-const defaultStatus = Status.default_();
+const defaultStatus = Status.defaultValue();
 console.log(defaultStatus); // "pending"
 ```
 
@@ -78,7 +109,7 @@ Default works with type aliases. For object types, it creates an object with def
 <MacroExample before={data.examples.typeAlias.before} after={data.examples.typeAlias.after} />
 
 ```typescript
-const dims = Dimensions.default_();
+const dims = Dimensions.defaultValue();
 console.log(dims); // { width: 0, height: 0 }
 ```
 
@@ -86,10 +117,10 @@ console.log(dims); // { width: 0, height: 0 }
 
 <InteractiveMacro code={`/** @derive(Default, Debug, Clone, PartialEq) */
 class User {
-  /** @defaultValue("Anonymous") */
+  /** @default("Anonymous") */
   name: string;
 
-  /** @defaultValue(0) */
+  /** @default(0) */
   age: number;
 
   constructor(name: string, age: number) {
@@ -99,7 +130,7 @@ class User {
 }`} />
 
 ```typescript
-const user1 = User.default();
+const user1 = User.defaultValue();
 const user2 = user1.clone();
 
 console.log(user1.toString());    // User { name: "Anonymous", age: 0 }

package/docs/custom-macros/ts-quote.md

@@ -20,6 +20,12 @@
 | `{| content |}` 
 | Ident block: concatenates without spaces (e.g., `{|get@{name}|}` → `getUser`) 
 
+| `&#123;> comment <&#125;` 
+| Block comment: outputs `/* comment */` 
+
+| `&#123;>> doc <<&#125;` 
+| Doc comment: outputs `/** doc */` (for JSDoc) 
+
 | `@@&#123;` 
 | Escape for literal `@&#123;` (e.g., `"@@&#123;foo&#125;"` → `@&#123;foo&#125;`) 
 
@@ -133,6 +139,73 @@ let action = "create";
 ts_template! { {|@{entity}_@{action}|} }  // → "user_create"
 ```
 
+## Comments: `&#123;> ... <&#125;` and `&#123;>> ... <<&#125;`
+
+Since Rust's tokenizer strips comments before macros see them, you can't write JSDoc comments directly. Instead, use the comment syntax to output JavaScript comments:
+
+### Block Comments
+
+Use `&#123;> comment <&#125;` for block comments:
+
+```rust
+let code = ts_template! {
+    {> This is a block comment <}
+    const x = 42;
+};
+```
+
+**Generates:**
+
+```typescript
+/* This is a block comment */
+const x = 42;
+```
+
+### Doc Comments (JSDoc)
+
+Use `&#123;>> doc <<&#125;` for JSDoc comments:
+
+```rust
+let code = ts_template! {
+    {>> @param {string} name - The user's name <<}
+    {>> @returns {string} A greeting message <<}
+    function greet(name: string): string {
+        return "Hello, " + name;
+    }
+};
+```
+
+**Generates:**
+
+```typescript
+/** @param {string} name - The user's name */
+/** @returns {string} A greeting message */
+function greet(name: string): string {
+    return "Hello, " + name;
+}
+```
+
+### Comments with Interpolation
+
+Comments support `@&#123;expr&#125;` interpolation for dynamic content:
+
+```rust
+let param_name = "userId";
+let param_type = "number";
+
+let code = ts_template! {
+    {>> @param {@{param_type}} @{param_name} - The user ID <<}
+    function getUser(userId: number) {}
+};
+```
+
+**Generates:**
+
+```typescript
+/** @param {number} userId - The user ID */
+function getUser(userId: number) {}
+```
+
 ## String Interpolation: `"text @&#123;expr&#125;"`
 
 Interpolation works automatically inside string literals - no `format!()` needed:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macroforge/mcp-server",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "MCP server for Macroforge documentation and code analysis",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "typescript": "^5.7.0"
   },
   "peerDependencies": {
-    "macroforge": "^0.1.23"
+    "macroforge": "^0.1.25"
   },
   "peerDependenciesMeta": {
     "macroforge": {