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)

1. If existing comment does not meet standards: Completely replace (no duplication)
2. 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

1. Partial success: When

• Fewer than 5 errors
• 90% or more of all comments meet standards

1. Failure: When

• melos analyze FAILED
• 5 or more errors