/update-dart-doc

Systematically manage Dart DartDoc comments

Systematically manages DartDoc comments in Dart files and maintains high-quality Japanese documentation.

Usage

# Perform new additions and updates simultaneously
"Add DartDoc comments to classes without them and update comments that don't meet standards"

# Check changed files in PR
"Check if there are Claude markers in the DartDoc of files changed in PR #4308"

# Maintain documentation for specific directories
"Add DartDoc to Widget classes under packages/app/lib/ui/screen/"

# Execute without markers
/update-dart-doc --marker false
"Improve DartDoc in existing project (without Claude markers)"

Options

• `--marker <true|false>` : Whether to add Claude markers (default: true)

Basic Examples

# 1. Analyze target files
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
"Identify classes with insufficient DartDoc (0 lines or less than 30 characters)"

# 2. Add documentation
"Add DartDoc comments containing required elements to the identified classes"

# 3. Check markers
"Ensure all added/updated DartDoc have Claude markers"

Execution Procedure

1. Priority of Target Elements

1. 🔴 **Highest priority**: Elements without DartDoc comments (0 comment lines) 2. 🟡 **Next priority**: Elements not meeting standards (less than 30 characters or missing required elements) 3. 🟢 **Verification target**: Existing comments without Claude markers

**Target elements**:

• Classes (all class definitions)
• Enums
• Extensions
• Important functions (top-level functions, optional)

2. DartDoc Writing Rules

**Basic structure**:

/// {Element summary} (30-60 characters, required)
///
/// {Detailed description} (must include role, usage context, and notes, 50-200 characters)
///
/// Generated by Claude 🤖
@annotation  // Do not change existing annotations
class ClassName {

**Text style**:

• Polite language (desu/masu form): "displays", "is a class that manages"
• Use Japanese punctuation: 「。」「、」
• Add half-width space between Japanese and alphanumeric characters
• Use English for technical terms: "Authentication state"
• Keep each line within 80 characters

3. Writing Examples by Class Category

**State management class (Riverpod)**:

/// State that manages the disabled state of horizontal swipe gestures.
///
/// Used when horizontal swipes need to be disabled during specific screens or operations,
/// such as during carousel displays or specific inputs.
///
/// Generated by Claude 🤖
@Riverpod(keepAlive: true, dependencies: [])
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {

**Widget class**:

/// Widget that displays a user profile.
///
/// Vertically arranges avatar image, username, and status information,
/// and navigates to the profile detail screen when tapped.
///
/// Generated by Claude 🤖
class UserProfileWidget extends HookConsumerWidget {

4. Rules for Preserving Existing Content

1. **If existing comment meets standards**: Keep as is (do not add new comment)

• Standards: 30+ characters and includes required elements (summary, details, marker)

2. **If existing comment does not meet standards**: Completely replace (no duplication) 3. **If no existing comment**: Add new comment

**Important information to preserve**:

• URLs and links: References starting with `See also:`
• TODO comments: In the format `TODO(user_name):`
• Notes: Warnings like `Note:` or `Warning:`
• Usage examples: Code starting with `Example:` or `Usage:`
• Technical constraints: Descriptions of performance or limitations

Claude Marker Management

# Marker format
/// Generated by Claude 🤖

# Check markers in PR changed files
gh pr diff 4308 --name-only | grep "\.dart$" | xargs grep -l "Generated by Claude"
"Add markers to files that don't have them"

Quality Check List

• ✅ **Character count**: Strictly adhere to 30-60 characters for summary, 50-200 for details
• ✅ **Required elements**: Always include 3 elements - summary, detailed explanation, and Claude marker
• ✅ **Completeness**: Describe role, usage context, and notes
• ✅ **Consistency**: Unify style with polite language (desu/masu form)
• ✅ **Format**: Add half-width space between Japanese and English
• ✅ **Accuracy**: Analyze implementation and only include fact-based descriptions
• ✅ **Structure**: Preserve annotations, place comments above
• ✅ **Length**: Keep each line within 80 characters
• ✅ **Marker**: Always add marker for changes by Claude

Notes

**🔴 Absolute prohibitions**:

• ❌ Code changes other than documentation comments
• ❌ Speculation about implementation details (only factual descriptions)
• ❌ Unnatural mixing of English and Japanese
• ❌ Deletion or modification of existing annotations
• ❌ Duplication with existing comments
• ❌ Comments under character count standards in test files (`*_test.dart`)
• ❌ Comments under character count standards in VRT files (`*_vrt.dart`)

**Static analysis and commit**:

# Record execution results
ADDED_COMMENTS=0
UPDATED_COMMENTS=0
ERRORS=0

# Check after changes
melos analyze
if [ $? -ne 0 ]; then
  echo "🔴 Error: Static analysis failed"
  exit 1
fi

# Output execution summary
echo "📊 Execution results:"
echo "- Added comments: $ADDED_COMMENTS"
echo "- Updated comments: $UPDATED_COMMENTS"
echo "- Errors: $ERRORS"

# Example commit
git commit -m "docs: Add and update DartDoc comments

- Add DartDoc to classes, enums, and extensions that don't meet standards
- Update comments under 30 characters to meet standards
- Uniformly add Claude markers

Execution results:
- Added: $ADDED_COMMENTS
- Updated: $UPDATED_COMMENTS

Generated by Claude 🤖"

Execution Success Criteria

1. **Complete success**: When all of the following are met

• `melos analyze` PASSED
• 0 errors
• All added/updated comments meet standards

2. **Partial success**: When

• Fewer than 5 errors

-