agy-superpowers 5.0.7 → 5.0.9

package/template/agent/skills/mobile-developer/references/android-rules/xml-to-compose-migration.md

@@ -0,0 +1,338 @@
+---
+name: xml-to-compose-migration
+description: Convert Android XML layouts to Jetpack Compose. Use when asked to migrate Views to Compose, convert XML to Composables, or modernize UI from View system to Compose.
+---
+
+# XML to Compose Migration
+
+## Overview
+
+Systematically convert Android XML layouts to idiomatic Jetpack Compose, preserving functionality while embracing Compose patterns. This skill covers layout mapping, state migration, and incremental adoption strategies.
+
+## Workflow
+
+### 1. Analyze the XML Layout
+
+- Identify the root layout type (`ConstraintLayout`, `LinearLayout`, `FrameLayout`, etc.).
+- List all View widgets and their key attributes.
+- Map data binding expressions (`@{}`) or view binding references.
+- Identify custom views that need special handling.
+- Note any `include`, `merge`, or `ViewStub` usage.
+
+### 2. Plan the Migration
+
+- Decide: **Full rewrite** or **incremental migration** (using `ComposeView`/`AndroidView`).
+- Identify state sources (ViewModel, LiveData, savedInstanceState).
+- List reusable components to extract as separate Composables.
+- Plan navigation integration if using Navigation component.
+
+### 3. Convert Layouts
+
+Apply the layout mapping table below to convert each View to its Compose equivalent.
+
+### 4. Migrate State
+
+- Convert `LiveData` observation to `StateFlow` collection or `observeAsState()`.
+- Replace `findViewById` / ViewBinding with Compose state.
+- Convert click listeners to lambda parameters.
+
+### 5. Test and Verify
+
+- Compare visual output between XML and Compose versions.
+- Test accessibility (content descriptions, touch targets).
+- Verify state preservation across configuration changes.
+
+---
+
+## Layout Mapping Reference
+
+### Container Layouts
+
+| XML Layout | Compose Equivalent | Notes |
+|------------|-------------------|-------|
+| `LinearLayout (vertical)` | `Column` | Use `Arrangement` and `Alignment` |
+| `LinearLayout (horizontal)` | `Row` | Use `Arrangement` and `Alignment` |
+| `FrameLayout` | `Box` | Children stack on top of each other |
+| `ConstraintLayout` | `ConstraintLayout` (Compose) | Use `createRefs()` and `constrainAs` |
+| `RelativeLayout` | `Box` or `ConstraintLayout` | Prefer Box for simple overlap |
+| `ScrollView` | `Column` + `Modifier.verticalScroll()` | Or use `LazyColumn` for lists |
+| `HorizontalScrollView` | `Row` + `Modifier.horizontalScroll()` | Or use `LazyRow` for lists |
+| `RecyclerView` | `LazyColumn` / `LazyRow` / `LazyGrid` | Most common migration |
+| `ViewPager2` | `HorizontalPager` | From accompanist or Compose Foundation |
+| `CoordinatorLayout` | Custom + `Scaffold` | Use `TopAppBar` with scroll behavior |
+| `NestedScrollView` | `Column` + `Modifier.verticalScroll()` | Prefer Lazy variants |
+
+### Common Widgets
+
+| XML Widget | Compose Equivalent | Notes |
+|------------|-------------------|-------|
+| `TextView` | `Text` | Use `style` → `TextStyle` |
+| `EditText` | `TextField` / `OutlinedTextField` | Requires state hoisting |
+| `Button` | `Button` | Use `onClick` lambda |
+| `ImageView` | `Image` | Use `painterResource()` or Coil |
+| `ImageButton` | `IconButton` | Use `Icon` inside |
+| `CheckBox` | `Checkbox` | Requires `checked` + `onCheckedChange` |
+| `RadioButton` | `RadioButton` | Use with `Row` for groups |
+| `Switch` | `Switch` | Requires state hoisting |
+| `ProgressBar (circular)` | `CircularProgressIndicator` | |
+| `ProgressBar (horizontal)` | `LinearProgressIndicator` | |
+| `SeekBar` | `Slider` | Requires state hoisting |
+| `Spinner` | `DropdownMenu` + `ExposedDropdownMenuBox` | More complex pattern |
+| `CardView` | `Card` | From Material 3 |
+| `Toolbar` | `TopAppBar` | Use inside `Scaffold` |
+| `BottomNavigationView` | `NavigationBar` | Material 3 |
+| `FloatingActionButton` | `FloatingActionButton` | Use inside `Scaffold` |
+| `Divider` | `HorizontalDivider` / `VerticalDivider` | |
+| `Space` | `Spacer` | Use `Modifier.size()` |
+
+### Attribute Mapping
+
+| XML Attribute | Compose Modifier/Property |
+|---------------|--------------------------|
+| `android:layout_width="match_parent"` | `Modifier.fillMaxWidth()` |
+| `android:layout_height="match_parent"` | `Modifier.fillMaxHeight()` |
+| `android:layout_width="wrap_content"` | `Modifier.wrapContentWidth()` (usually implicit) |
+| `android:layout_weight` | `Modifier.weight(1f)` |
+| `android:padding` | `Modifier.padding()` |
+| `android:layout_margin` | `Modifier.padding()` on parent, or use `Arrangement.spacedBy()` |
+| `android:background` | `Modifier.background()` |
+| `android:visibility="gone"` | Conditional composition (don't emit) |
+| `android:visibility="invisible"` | `Modifier.alpha(0f)` (keeps space) |
+| `android:clickable` | `Modifier.clickable { }` |
+| `android:contentDescription` | `Modifier.semantics { contentDescription = "" }` |
+| `android:elevation` | `Modifier.shadow()` or component's `elevation` param |
+| `android:alpha` | `Modifier.alpha()` |
+| `android:rotation` | `Modifier.rotate()` |
+| `android:scaleX/Y` | `Modifier.scale()` |
+| `android:gravity` | `Alignment` parameter or `Arrangement` |
+| `android:layout_gravity` | `Modifier.align()` |
+
+---
+
+## Common Patterns
+
+### LinearLayout with Weights
+
+```xml
+<!-- XML -->
+<LinearLayout android:orientation="horizontal">
+    <View android:layout_weight="1" />
+    <View android:layout_weight="2" />
+</LinearLayout>
+```
+
+```kotlin
+// Compose
+Row(modifier = Modifier.fillMaxWidth()) {
+    Box(modifier = Modifier.weight(1f))
+    Box(modifier = Modifier.weight(2f))
+}
+```
+
+### RecyclerView to LazyColumn
+
+```xml
+<!-- XML -->
+<androidx.recyclerview.widget.RecyclerView
+    android:id="@+id/recyclerView"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent" />
+```
+
+```kotlin
+// Compose
+LazyColumn(modifier = Modifier.fillMaxSize()) {
+    items(items, key = { it.id }) { item ->
+        ItemRow(item = item, onClick = { onItemClick(item) })
+    }
+}
+```
+
+### EditText with Two-Way Binding
+
+```xml
+<!-- XML with Data Binding -->
+<EditText
+    android:text="@={viewModel.username}"
+    android:hint="@string/username_hint" />
+```
+
+```kotlin
+// Compose
+val username by viewModel.username.collectAsState()
+
+OutlinedTextField(
+    value = username,
+    onValueChange = { viewModel.updateUsername(it) },
+    label = { Text(stringResource(R.string.username_hint)) },
+    modifier = Modifier.fillMaxWidth()
+)
+```
+
+### ConstraintLayout Migration
+
+```xml
+<!-- XML -->
+<androidx.constraintlayout.widget.ConstraintLayout>
+    <TextView
+        android:id="@+id/title"
+        app:layout_constraintTop_toTopOf="parent"
+        app:layout_constraintStart_toStartOf="parent" />
+    <TextView
+        android:id="@+id/subtitle"
+        app:layout_constraintTop_toBottomOf="@id/title"
+        app:layout_constraintStart_toStartOf="@id/title" />
+</androidx.constraintlayout.widget.ConstraintLayout>
+```
+
+```kotlin
+// Compose
+ConstraintLayout(modifier = Modifier.fillMaxWidth()) {
+    val (title, subtitle) = createRefs()
+    
+    Text(
+        text = "Title",
+        modifier = Modifier.constrainAs(title) {
+            top.linkTo(parent.top)
+            start.linkTo(parent.start)
+        }
+    )
+    Text(
+        text = "Subtitle", 
+        modifier = Modifier.constrainAs(subtitle) {
+            top.linkTo(title.bottom)
+            start.linkTo(title.start)
+        }
+    )
+}
+```
+
+### Include / Merge → Extract Composable
+
+```xml
+<!-- XML: layout_header.xml -->
+<merge>
+    <ImageView android:id="@+id/avatar" />
+    <TextView android:id="@+id/name" />
+</merge>
+
+<!-- Usage -->
+<include layout="@layout/layout_header" />
+```
+
+```kotlin
+// Compose: Extract as a reusable Composable
+@Composable
+fun HeaderSection(
+    avatarUrl: String,
+    name: String,
+    modifier: Modifier = Modifier
+) {
+    Row(modifier = modifier) {
+        AsyncImage(model = avatarUrl, contentDescription = null)
+        Text(text = name)
+    }
+}
+
+// Usage
+HeaderSection(avatarUrl = user.avatar, name = user.name)
+```
+
+---
+
+## Incremental Migration (Interop)
+
+### Embedding Compose in XML
+
+```xml
+<!-- In your XML layout -->
+<androidx.compose.ui.platform.ComposeView
+    android:id="@+id/compose_view"
+    android:layout_width="match_parent"
+    android:layout_height="wrap_content" />
+```
+
+```kotlin
+// In Fragment/Activity
+binding.composeView.setContent {
+    MaterialTheme {
+        MyComposable()
+    }
+}
+```
+
+### Embedding XML Views in Compose
+
+```kotlin
+// Use AndroidView for Views that don't have Compose equivalents
+@Composable
+fun MapViewComposable(modifier: Modifier = Modifier) {
+    AndroidView(
+        factory = { context ->
+            MapView(context).apply {
+                // Initialize the view
+            }
+        },
+        update = { mapView ->
+            // Update the view when state changes
+        },
+        modifier = modifier
+    )
+}
+```
+
+---
+
+## State Migration
+
+### LiveData to Compose
+
+```kotlin
+// Before: Observing in Fragment
+viewModel.uiState.observe(viewLifecycleOwner) { state ->
+    binding.title.text = state.title
+}
+
+// After: Collecting in Compose
+@Composable
+fun MyScreen(viewModel: MyViewModel = hiltViewModel()) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+    
+    Text(text = uiState.title)
+}
+```
+
+### Click Listeners
+
+```kotlin
+// Before: XML + setOnClickListener
+binding.submitButton.setOnClickListener {
+    viewModel.submit()
+}
+
+// After: Lambda in Compose
+Button(onClick = { viewModel.submit() }) {
+    Text("Submit")
+}
+```
+
+---
+
+## Checklist
+
+- [ ] All layouts converted (no `include` or `merge` left)
+- [ ] State hoisted properly (no internal mutable state for user input)
+- [ ] Click handlers converted to lambdas
+- [ ] RecyclerView adapters removed (using LazyColumn/LazyRow)
+- [ ] ViewBinding/DataBinding removed
+- [ ] Navigation integrated (NavHost or interop)
+- [ ] Theming applied (MaterialTheme)
+- [ ] Accessibility preserved (content descriptions, touch targets)
+- [ ] Preview annotations added for development
+- [ ] Old XML files deleted
+
+## References
+
+- [Interoperability APIs](https://developer.android.com/develop/ui/compose/migrate/interoperability-apis)
+- [Migration Strategy](https://developer.android.com/develop/ui/compose/migrate/strategy)
+- [Compose and Views side by side](https://developer.android.com/develop/ui/compose/migrate)

package/template/agent/skills/mobile-developer/references/flutter-rules/dart-best-practices.md

@@ -0,0 +1,52 @@
+---
+name: dart-best-practices
+description: |-
+  General best practices for Dart development.
+  Covers code style, effective Dart, and language features.
+license: Apache-2.0
+---
+
+# Dart Best Practices
+
+## 1. When to use this skill
+Use this skill when:
+-   Writing or reviewing Dart code.
+-   Looking for guidance on idiomatic Dart usage.
+
+## 2. Best Practices
+
+### Multi-line Strings
+Prefer using multi-line strings (`'''`) over concatenating strings with `+` and
+`\n`, especially for large blocks of text like SQL queries, HTML, or
+PEM-encoded keys. This improves readability and avoids
+`lines_longer_than_80_chars` lint errors by allowing natural line breaks.
+
+**Avoid:**
+```dart
+final pem = '-----BEGIN RSA PRIVATE KEY-----\n' +
+    base64Encode(fullBytes) +
+    '\n-----END RSA PRIVATE KEY-----';
+```
+
+**Prefer:**
+```dart
+final pem = '''
+-----BEGIN RSA PRIVATE KEY-----
+${base64Encode(fullBytes)}
+-----END RSA PRIVATE KEY-----''';
+```
+
+### Line Length
+Avoid lines longer than 80 characters, even in Markdown files and comments.
+This ensures code is readable in split-screen views and on smaller screens
+without horizontal scrolling.
+
+**Prefer:**
+Target 80 characters for wrapping text. Exceptions are allowed for long URLs
+or identifiers that cannot be broken.
+
+## Related Skills
+
+- **[`dart-modern-features`](../dart-modern-features/SKILL.md)**: For idiomatic
+  usage of modern Dart features like Pattern Matching (useful for deep JSON
+  extraction), Records, and Switch Expressions.

package/template/agent/skills/mobile-developer/references/flutter-rules/dart-checks-migration.md

@@ -0,0 +1,134 @@
+---
+name: dart-checks-migration
+description: |-
+  Replace the usage of `expect` and similar functions from `package:matcher`
+  to `package:checks` equivalents.
+license: Apache-2.0
+---
+
+# Dart Checks Migration
+
+## When to use this skill
+Use this skill when:
+- Migrating existing test files from `package:matcher` to `package:checks`.
+- A user specifically asks for "modern checks" or similar.
+
+## The Workflow
+
+1.  **Analysis**:
+    - Use `grep` to identify files using `expect` or `package:matcher`.
+    - Review custom matchers; these may require manual migration.
+2.  **Tools & Dependencies**:
+    - Ensure `dev_dependencies` includes `checks`.
+    - Run `dart pub add --dev checks` if missing.
+3.  **Discovery**:
+    - Use the **Strategies for Discovery** below to find candidates.
+4.  **Replacement**:
+    - Add `import 'package:checks/checks.dart';`.
+    - Apply the **Common Patterns** below.
+    - **Final Step**: Replace `import 'package:test/test.dart';` with
+      `import 'package:test/scaffolding.dart';` ONLY after all `expect` calls
+      are replaced. This ensures incremental progress.
+5.  **Verification**:
+    - Ensure the code analyzes cleanly.
+    - Ensure tests pass.
+
+## Common Patterns
+
+| Legacy `expect` | Modern `check` |
+| :--- | :--- |
+| `expect(a, equals(b))` | `check(a).equals(b)` |
+| `expect(a, isTrue)` | `check(a).isTrue()` |
+| `expect(a, isFalse)` | `check(a).isFalse()` |
+| `expect(a, isNull)` | `check(a).isNull()` |
+| `expect(a, isNotNull)` | `check(a).isNotNull()` |
+| `expect(() => fn(), throwsA<T>())` | `check(() => fn()).throws<T>()` |
+| `expect(list, hasLength(n))` | `check(list).length.equals(n)` |
+| `expect(a, closeTo(b, delta))` | `check(a).isA<num>().isCloseTo(b, delta)` |
+| `expect(a, greaterThan(b))` | `check(a).isGreaterThan(b)` |
+| `expect(a, lessThan(b))` | `check(a).isLessThan(b)` |
+| `expect(list, isEmpty)` | `check(list).isEmpty()` |
+| `expect(list, isNotEmpty)` | `check(list).isNotEmpty()` |
+| `expect(list, contains(item))` | `check(list).contains(item)` |
+| `expect(map, equals(otherMap))` | `check(map).deepEquals(otherMap)` |
+| `expect(list, equals(otherList))` | `check(list).deepEquals(otherList)` |
+| `expect(future, completes)` | `await check(future).completes()` |
+| `expect(stream, emitsInOrder(...))` | `await check(stream).withQueue.inOrder(...)` |
+
+### Async & Futures (CRITICAL)
+
+- **Checking async functions:**
+  `check(() => asyncFunc()).throws<T>()` causes **FALSE POSITIVES** because the
+  closure returns a `Future`, which is a value, so it "completes normally"
+  (as a Future).
+  **Correct Usage:**
+  ```dart
+  await check(asyncFunc()).throws<T>();
+  ```
+
+- **Chaining on void returns:**
+  Many async check methods (like `throws`) return `Future<void>`. You cannot
+  chain directly on them. Use cascades or callbacks.
+  **Wrong:**
+  ```dart
+  await check(future).throws<Error>().has((e) => e.message, 'message').equals('foo');
+  ```
+  **Correct:**
+  ```dart
+  await check(future).throws<Error>((it) => it.has((e) => e.message, 'message').equals('foo'));
+  ```
+
+## Complex Examples
+
+*Deep Verification with `isA` and `having`:*
+
+**Legacy:**
+```dart
+expect(() => foo(), throwsA(isA<ArgumentError>()
+    .having((e) => e.message, 'message', contains('MSG'))));
+```
+
+**Modern:**
+```dart
+check(() => foo())
+    .throws<ArgumentError>()
+    .has((e) => e.message, 'message')
+    .contains('MSG');
+```
+
+*Property Extraction:*
+
+**Legacy:**
+```dart
+expect(obj.prop, equals(value)); // When checking multiple props
+```
+
+**Modern:**
+```dart
+check(obj)
+  ..has((e) => e.prop, 'prop').equals(value)
+  ..has((e) => e.other, 'other').equals(otherValue);
+```
+
+*One-line Cascades:*
+Since checks often return `void`, use cascades for multiple assertions on the
+same subject.
+```dart
+check(it)..isGreaterThan(10)..isLessThan(20);
+```
+
+## Constraints
+
+- **Scope**: Only modify files in `test/` (and `pubspec.yaml`).
+- **Correctness**: One failing test is unacceptable. If a test fails after
+  migration and you cannot fix it immediately, REVERT that specific change.
+- **Type Safety**: `package:checks` is stricter about types than `matcher`.
+  You may need to add explicit `as T` casts or `isA<T>()` checks in the chain.
+
+## Related Skills
+
+- **[`dart-test-fundamentals`](../dart-test-fundamentals/SKILL.md)**: Core
+  concepts for structuring tests, lifecycles, and configuration.
+- **[`dart-matcher-best-practices`](../dart-matcher-best-practices/SKILL.md)**:
+  Best practices for the traditional `package:matcher` that is being migrated
+  away from.

package/template/agent/skills/mobile-developer/references/flutter-rules/dart-cli-app-best-practices.md

@@ -0,0 +1,123 @@
+---
+name: dart-cli-app-best-practices
+description: |-
+  Best practices for creating high-quality, executable Dart CLI applications.
+  Covers entrypoint structure, exit code handling, and recommended packages.
+license: Apache-2.0
+---
+
+# Dart CLI Application Best Practices
+
+## 1. When to use this skill
+Use this skill when:
+-   Creating a new Dart CLI application.
+-   Refactoring an existing CLI entrypoint (`bin/`).
+-   Reviewing CLI code for quality and standards.
+-   Setting up executable scripts for Linux/Mac.
+
+## 2. Best Practices
+
+### Entrypoint Structure (`bin/`)
+Keep the contents of your entrypoint file (e.g., `bin/my_app.dart`) minimal.
+This improves testability by decoupling logic from the process runner.
+
+**DO:**
+```dart
+// bin/my_app.dart
+import 'package:my_app/src/entry_point.dart';
+
+Future<void> main(List<String> arguments) async {
+  await runApp(arguments);
+}
+```
+
+**DON'T:**
+-   Put complex logic directly in `bin/my_app.dart`.
+-   Define classes or heavy functions in the entrypoint.
+
+### Executable Scripts
+For CLI tools intended to be run directly on Linux and Mac, add a shebang and
+ensure the file is executable.
+
+**DO:**
+1.  Add `#!/usr/bin/env dart` to the first line.
+2.  Run `chmod +x bin/my_script.dart` to make it executable.
+
+```dart
+#!/usr/bin/env dart
+
+void main() => print('Ready to run!');
+```
+
+### Process Termination (`exitCode`)
+Properly handle process termination to allow for debugging and correct status
+reporting.
+
+**DO:**
+-   Use the `exitCode` setter to report failure.
+-   Allow `main` to complete naturally.
+-   Use standard exit codes (sysexits) for clarity (e.g., `64` for bad usage,
+    `78` for configuration errors).
+    -   See `package:io` `ExitCode` class or FreeBSD sysexits man page.
+
+```dart
+import 'dart:io';
+
+void main() {
+  if (someFailure) {
+    exitCode = 64; // DO!
+    return;
+  }
+}
+```
+
+**AVOID:**
+-   Calling `exit(code)` directly, as it terminates the VM immediately,
+    preventing "pause on exit" debugging and `finally` blocks from running.
+
+### Exception Handling
+Uncaught exceptions automatically set a non-zero exit code, but you should
+handle expected errors gracefully.
+
+**Example:**
+```dart
+Future<void> main(List<String> arguments) async {
+  try {
+    await runApp(arguments);
+  } catch (e, stack) {
+    print('App crashed!');
+    print(e);
+    print(stack);
+    exitCode = 1; // Explicitly fail
+  }
+}
+```
+
+## 3. Recommended Packages
+
+Use these community-standard packages owned by the [Dart team](https://dart.dev)
+to solve common CLI problems:
+
+| Category | Recommended Package | Usage |
+| :--- | :--- | :--- |
+| **Stack Traces** | [`package:stack_trace`](https://pub.dev/packages/stack_trace) | detailed, cleaner stack traces |
+| **Arg Parsing** | [`package:args`](https://pub.dev/packages/args) | standard flag/option parsing |
+| **Testing** | [`package:test_process`](https://pub.dev/packages/test_process) | integration testing for CLI apps |
+| **Testing** | [`package:test_descriptor`](https://pub.dev/packages/test_descriptor) | file system fixtures for tests |
+| **Networking** | [`package:http`](https://pub.dev/packages/http) | standard HTTP client (remember user-agent!) |
+| **ANSI Output** | [`package:io`](https://pub.dev/packages/io) | handling ANSI colors and styles |
+
+## 4. Interesting community packages
+
+| Category | Recommended Package | Usage |
+| :--- | :--- | :--- |
+| **Configuration** | [`package:json_serializable`](https://pub.dev/packages/json_serializable) | strongly typed config objects |
+| **CLI Generation** | [`package:build_cli`](https://pub.dev/packages/build_cli) | generate arg parsers from classes |
+| **Version Info** | [`package:build_version`](https://pub.dev/packages/build_version) | automatic version injection |
+| **Configuration** | [`package:checked_yaml`](https://pub.dev/packages/checked_yaml) | precise YAML parsing with line numbers |
+
+## 5. Conventions
+
+-   **File Caching**: Write cached files to `.dart_tool/[pkg_name]/`.
+-   **User-Agent**: Always set a User-Agent header in HTTP requests, including
+    version info.

package/template/agent/skills/mobile-developer/references/flutter-rules/dart-doc-validation.md

@@ -0,0 +1,45 @@
+---
+name: dart-doc-validation
+description: |-
+  Best practices for validating Dart documentation comments.
+  Covers using `dart doc` to catch unresolved references and macros.
+license: Apache-2.0
+---
+
+# Dart Doc Validation
+
+## 1. When to use this skill
+
+Use this skill when:
+-   Writing or updating documentation comments (`///`) in Dart code.
+-   Checking for broken documentation links, references, or macros.
+-   Preparing a package for publishing to pub.dev.
+
+## 2. Best Practices
+
+### Validating Documentation Locally
+
+Use the `dart doc` command with a temporary output directory to validate
+documentation comments without polluting the local project workspace.
+
+This command parses all documentation comments and reports warnings such as:
+-   `warning: unresolved doc reference`
+-   `warning: undefined macro`
+
+**Command to run:**
+```bash
+dart doc -o $(mktemp -d)
+```
+
+This ensures that the generated HTML files are stored in a temporary location
+and don't clutter the package directory, while still surfacing all validation
+warnings in the terminal output.
+
+### Fixing Common Warnings
+
+-   **Unresolved doc reference**: Ensure that any identifier wrapped in square
+    brackets (`[Identifier]`) correctly points to an existing class, method,
+    property, or parameter in the current scope or imported libraries.
+-   **Undefined macro**: If using `{@macro macro_name}`, ensure that the
+    template `{@template macro_name}` is defined in the same file or a file
+    that is imported and visible to the documentation generator.