Generated keys documentation

[PWrzesinski]

It would be useful if the generated keys contained the translations from the original file as docs, so for example when I hover the cursor over the key in VSCode I can see the translation. That would save a lot of time switching back and forth between the code and the localizations file.

For example (in the generated file):

/// "Settings"
static const main_menu_settings_button_title = 'main_menu.settings_button.title';

This feature could be optional with a parameter provided to the generator.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

🔗 Similar Issues

Related Issues

• Add an export statement for the public extensions in the LocaleKeys class #780

👤 Suggested Assignees

• rekire

---

🧪 Issue enrichment is currently in early access.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

[coderabbitai]

Coding Plan

Summary

• Add a single opt-in CLI flag (--with-doc-comments / -d) that defaults to false, preserving backward compatibility
• Thread the flag through the existing function call chain following the established pattern used by skip-unnecessary-keys
• Modify _resolve() to conditionally emit /// "value" doc comments only for leaf string translations, skipping complex nested structures
• All changes are isolated to bin/generate.dart with no impact on runtime library code

Design Choices

Design Choice 1: How should doc comments be handled for non-string values (plural/gender maps)?

Options Considered:

1. Only emit doc comments for leaf string values (skip for Map-typed values)
2. Emit a placeholder like [nested] or [plural] for map values
3. Extract and display the first sub-value from plural/gender maps

Chosen Option: 1

Rationale: Only emit doc comments for string leaf values, as this matches the ticket example and provides the most useful, unambiguous information.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Add CLI Flag Infrastructure

This phase establishes the command-line interface for the new feature and ensures the flag value is accessible throughout the generation pipeline.

Task 1: Define the New CLI Flag and Options Field

Add a new boolean flag to enable doc comment generation, following the existing pattern established by --skip-unnecessary-keys.

• Add --with-doc-comments flag (abbr: -d) in _generateArgParser() after the existing skip-unnecessary-keys flag, with defaultsTo: false and appropriate help text
• Add bool? withDocComments field to the GenerateOptions class alongside existing fields like skipUnnecessaryKeys
• Wire the callback to set generateOptions.withDocComments = x

Task 2: Thread the Flag Through the Call Chain

Ensure the new flag value is passed to all functions that need it, mirroring the existing pattern for skipUnnecessaryKeys.

• Update _writeKeys() signature to accept the withDocComments parameter
• Update _resolve() signature to accept the withDocComments parameter
• Modify the call from generateFile() to _writeKeys() to pass the flag
• Modify the call from _writeKeys() to _resolve() to pass the flag

🤖 Prompt for AI agents

This phase adds the CLI flag `--with-doc-comments` to `bin/generate.dart` and
threads it through the generation pipeline, following the same pattern as
`skipUnnecessaryKeys`.

- In `_generateArgParser()`, add a new boolean flag `--with-doc-comments` (abbr:
`-d`) after the existing `skip-unnecessary-keys` flag, with `defaultsTo: false`
and appropriate help text
- In the `GenerateOptions` class, add a `bool? withDocComments` field alongside
existing fields like `skipUnnecessaryKeys`
- Wire the callback to set `generateOptions.withDocComments = x`
- Update the `_writeKeys()` function signature to accept a `withDocComments`
parameter
- Update the `_resolve()` function signature to accept a `withDocComments`
parameter
- Update the call from `generateFile()` to `_writeKeys()` to pass the flag value
- Update the call from `_writeKeys()` to `_resolve()` to pass the flag value

Phase 2: Implement Doc Comment Generation

This phase adds the core logic to emit doc comments containing translation values when the flag is enabled.

Emit Doc Comments in _resolve()

Modify the constant emission logic in _resolve() to conditionally prepend doc comments showing the translation value.

• Before each static const emission line, check if withDocComments is true AND translations[key] is a String (not a Map)
• When both conditions are met, emit a doc comment line in the format /// "translation_value" before the constant
• Handle special characters in translation strings: escape or replace newlines with spaces to prevent broken doc comments, and escape internal double quotes if present
• Maintain the existing behavior when the flag is false or when the value is a Map (no doc comment emitted)

The resulting output for a key with value "Settings" would be:

  /// "Settings"
  static const main_menu_settings_button_title = 'main_menu.settings_button.title';

🤖 Prompt for AI agents

This phase modifies the `_resolve()` function in `bin/generate.dart` to
conditionally emit `/// "value"` doc comments above each `static const` line
when the `--with-doc-comments` flag is enabled.

- In `_resolve()`, before each `static const` emission line:
- Check if `withDocComments` is `true` AND `translations[key]` is a `String`
(not a `Map`)
- When both conditions are met, emit a doc comment line in the format `  ///
"translation_value"` immediately before the constant line
- Handle special characters in translation strings:
  - Replace newlines with spaces to prevent broken doc comments
  - Escape internal double quotes if present
- When the flag is `false` or the value is a `Map`, emit no doc comment
(preserve existing behavior)

Example output for a key with value `"Settings"`:
```dart
  /// "Settings"
static const main_menu_settings_button_title =
'main_menu.settings_button.title';
```

Research

The code generator is entirely self-contained in bin/generate.dart (~292 lines) with no dependencies on lib/src/ for codegen logic. The generator reads JSON translation files from a source directory, and when --format keys is specified, it emits an abstract class LocaleKeys with static const string fields. The _resolve() function recursively traverses the JSON structure, building constant definitions with dot-separated paths for nested keys. Command-line options are defined in _generateArgParser() and stored in a GenerateOptions class, then threaded through handleLangFiles → generateFile → _writeKeys → _resolve.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase adds the CLI flag `--with-doc-comments` to `bin/generate.dart` and
threads it through the generation pipeline, following the same pattern as
`skipUnnecessaryKeys`.

- In `_generateArgParser()`, add a new boolean flag `--with-doc-comments` (abbr:
`-d`) after the existing `skip-unnecessary-keys` flag, with `defaultsTo: false`
and appropriate help text
- In the `GenerateOptions` class, add a `bool? withDocComments` field alongside
existing fields like `skipUnnecessaryKeys`
- Wire the callback to set `generateOptions.withDocComments = x`
- Update the `_writeKeys()` function signature to accept a `withDocComments`
parameter
- Update the `_resolve()` function signature to accept a `withDocComments`
parameter
- Update the call from `generateFile()` to `_writeKeys()` to pass the flag value
- Update the call from `_writeKeys()` to `_resolve()` to pass the flag value
===============================================================================

Task: 2

This phase modifies the `_resolve()` function in `bin/generate.dart` to
conditionally emit `/// "value"` doc comments above each `static const` line
when the `--with-doc-comments` flag is enabled.

- In `_resolve()`, before each `static const` emission line:
- Check if `withDocComments` is `true` AND `translations[key]` is a `String`
(not a `Map`)
- When both conditions are met, emit a doc comment line in the format `  ///
"translation_value"` immediately before the constant line
- Handle special characters in translation strings:
  - Replace newlines with spaces to prevent broken doc comments
  - Escape internal double quotes if present
- When the flag is `false` or the value is a `Map`, emit no doc comment
(preserve existing behavior)

Example output for a key with value `"Settings"`:
```dart
  /// "Settings"
static const main_menu_settings_button_title =
'main_menu.settings_button.title';
```

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[rekire]

What's going on here? The AI wants to assign this to me?

[PWrzesinski]

What's going on here? The AI wants to assign this to me?

Looks like just a suggestion, you can safely ignore. I will probably implement this myself at some point, just need to find a moment.

[rekire]

I was just kidding, I was just surprised :-)