Initial commit
This commit is contained in:
Zhongwei Li
202
commands/update-dart-doc.md
Normal file
202
commands/update-dart-doc.md
Normal file
@@ -0,0 +1,202 @@
|
||||
## Update Dart Doc
|
||||
|
||||
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
|
||||
Reference in New Issue
Block a user