flutter-dartdoc

When to Use

• Writing /// doc comments on classes, methods, properties, or top-level functions
• Reviewing existing documentation for completeness
• Generating API docs with dart doc
• Enforcing documentation linting rules

---

Critical Rules

Rule	Description
Use /// not /** */	Dart convention uses triple-slash, not block comments
First sentence is a summary	Must be a single, concise sentence ending in .
Start with a verb (methods)	/// Returns, /// Creates, /// Throws
Start with a noun (classes)	/// A button that..., /// Repository for...
Document the WHY, not the WHAT	Code shows what; docs explain why and when
No redundant docs	Don't document obvious getters/setters unless they have side effects

---

Class Documentation

See assets/class_doc.dart

---

Method Documentation

See assets/method_doc.dart

---

Parameter Documentation

Use [paramName] in prose — DartDoc auto-links them:

See assets/parameter_doc.dart

DO NOT use @param tags — that's JSDoc, not DartDoc.

---

Property Documentation

See assets/property_doc.dart

Skip docs for trivially obvious properties:

// No doc needed — name is self-evident
final String name;

---

Enum Documentation

See assets/enum_doc.dart

---

Widget Documentation

See assets/widget_doc.dart

---

What NOT to Document

See assets/anti_patterns.dart

---

Markdown in DartDoc

DartDoc supports Markdown:

Feature	Syntax
Code inline	`code`
Code block	/// ```dart ... ```
Links to types	[ClassName], [method]
External links	[text](url)
Lists	/// - item or /// 1. item
Headers	/// ## Section
Bold	/// **bold**

---

Linting Rules

Add to analysis_options.yaml:

See assets/analysis_options.yaml

Recommended Minimum

For a new project, start with slash_for_doc_comments and comment_references. Add public_member_api_docs once the codebase is stable — it's strict.

---

Generating Docs

# Generate HTML docs
dart doc .

# Output lands in doc/api/
open doc/api/index.html

---

Checklist

• Every public class has a /// summary
• Every public method has a /// summary with return/throw info
• First sentence is concise and ends in .
• Parameters referenced with [paramName] in prose
• No @param, @return, @throws tags (that's JSDoc)
• No redundant docs on obvious properties
• Code examples use /// ```dart blocks
• [TypeReferences] are valid and resolvable