Update Dart Doc

---
description: 'Systematically manage Dart DartDoc comments. Trigger with "update DartDoc", "manage Dart documentation", "add DartDoc".'
allowed-tools:
  - Read
  - Edit
  - Grep
  - Glob
---

# Systematically manage Dart DartDoc comments

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

## Usage

```bash
# 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

```bash
# 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**:

```dart
/// {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)**:

```dart
/// 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**:

```dart
/// 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

```bash
# 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**:

```bash
# 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
   - 90% or more of all comments meet standards

3. **Failure**: When
   - `melos analyze` FAILED
   - 5 or more errors