Masamune Model Docs Builder

---

[GitHub](https://github.com/mathrunet) | [YouTube](https://www.youtube.com/c/mathrunetchannel) | [Packages](https://pub.dev/publishers/mathru.net/packages) | [X](https://x.com/mathru) | [LinkedIn](https://www.linkedin.com/in/mathrunet/) | [mathru.net](https://mathru.net)

---

Masamune Model Docs Builder

Usage

Installation

1. Add the builder as a development dependency.

flutter pub add --dev masamune_model_docs_builder
flutter pub add --dev build_runner

Generate Documentation

2. Annotate your models with standard Masamune annotations:

// lib/models/user.dart

@freezed
@formValue
@immutable
@CollectionModelPath('user')
class UserModel with _$UserModel {
  const factory UserModel({
    /// User's display name
    required String name,
    
    /// User's email address
    @Default('') String email,
    
    /// Timestamp when the user was created
    @Default(ModelTimestamp.now()) ModelTimestamp createdAt,
  }) = _UserModel;
  // ... rest of the model
}

3. Run the code generator:

katana code generate

This generates Markdown documentation files in docs/model/ with:

• Model name and type (Collection/Document)
• Field names, types, and descriptions
• Default values and constraints

Generated Documentation Example

The builder creates files like docs/model/user.md:

# UserModel

Type: Collection
Path: `user`

## Fields

| Field Name | Type | Required | Default | Description |
|------------|------|----------|---------|-------------|
| name | String | Yes | - | User's display name |
| email | String | No | '' | User's email address |
| createdAt | ModelTimestamp | No | now() | Timestamp when the user was created |

Customize Output

Configure the output directory in build.yaml:

targets:
  $default:
    builders:
      masamune_model_docs_builder:
        options:
          output_dir: "docs/model"  # Default output directory

Use Cases

• Team Documentation: Keep database schemas documented and in sync with code
• API Documentation: Generate reference docs for your backend API
• Onboarding: Help new developers understand data models
• Version Control: Track schema changes over time in git history

Tips

• Run katana code generate after model changes to update docs
• Commit generated docs to version control
• Use detailed Dart doc comments on fields for better documentation
• Integrate with your CI/CD to ensure docs stay up-to-date

GitHub Sponsors

Sponsors are always welcome. Thank you for your support!

https://github.com/sponsors/mathrunet