/code-documentation

Dart & Flutter Documentation

Documentation Structure (///)

Use /// (doc comments) for all public members to allow tools like dartdoc to process them.

Comments Format

1. Summary Sentence: Start with a single-sentence summary on the first line, ending with a period.
2. Blank Line: Follow the summary with a blank line.
3. Details: Add paragraphs, code samples, or lists as needed to explain parameters, return values, exceptions, and behavior.
4. Annotations: Place doc comments before any metadata annotations (e.g., @override, @Deprecated).

/// A button that initiates a purchase flow.
///
/// This widget handles the loading state automatically and disables
/// itself while the transaction is processing.
@Deprecated('Use PurchaseButtonV2 instead')
class PurchaseButton extends StatelessWidget { ... }

Property Documentation

• Getters override Setters: Document the getter and omit documentation on the setter, as documentation tools combine them automatically. Do not document both.

  /// The current optimization level (0.0 to 1.0).
  double get optimizationLevel => _level;
  set optimizationLevel(double value) { ... }

Library Documentation

• Library Comments: Add a doc comment at the top of the file (before imports) for libraries (files) to provide a high-level overview.

Writing Guidelines

Terminology

• Use canonical terms:
  • Refer to "widgets", "state", "build context", "render object".
  • Avoid generic terms like "component" or "element" when you mean "Widget".

Code References

• Use square brackets [MyClass], [variableName], [methodName] to link to in-scope identifiers.
• Use backticks `true`, `null`, `this` for keywords and literals.
• Code Samples: Include code blocks to demonstrate usage.

  /// Example:
  ///
  /// ```dart
  /// final path = FlightPath(coordinates: [a, b]);
  /// ```

Flutter Specifics

Widgets

• Purpose: Explain what the widget does and when to use it.
• Parameters: Document key parameters, especially if they are required or have complex constraints.
• State: Explain any interesting state behavior, such as keeping position on scroll.

/// Displays a flight path on a map.
///
/// Use this widget within a [MapLayout]. The path is drawn using
/// the provided [coordinates].
class FlightPath extends StatelessWidget {
  /// Creates a flight path.
  ///
  /// The [coordinates] must contain at least two points.
  const FlightPath({required this.coordinates, super.key});

State Management

• Lifecycle: Explain how to dispose of controllers or other classes that manage a complex lifecycle.
• Private Classes: Document significantly complex private classes (such as intricate State logic) to aid maintainability, even though public APIs are the priority.