Dart Documentation Comment

/// This is the idiomatic Dart documentation comment syntax.
/// Each line begins with three forward slashes.
String? idiomaticDoc;

/**
 * This is the legacy block documentation comment syntax.
 * It is supported by the compiler but discouraged by the linter.
 */
String? legacyDoc;

// This is a standard comment. It is ignored by the dart doc compiler.
String? undocumented;

/// Authenticates the user against the primary identity provider.
///
/// This method initiates a network request. If the network is unavailable,
/// it will retry up to 3 times before failing.
///
/// Required parameters:
/// * [username] The user's registered email address.
/// * [password] The plaintext password.
///
/// ```dart
/// final auth = Authenticator();
/// await auth.login('user@example.com', 'superSecret');
/// ```
Future<void> login(String username, String password) async { /* ... */ }

/// Updates the [status] of the [Transaction].
///
/// If [status] is [TransactionStatus.failed], this triggers [rollback].
void updateStatus(TransactionStatus status) { /* ... */ }

/// {@template base_http_exception}
/// Thrown when an HTTP request fails at the transport layer.
/// {@endtemplate}
class HttpException implements Exception {}

/// {@macro base_http_exception}
///
/// Specifically indicates a 404 Not Found response.
class NotFoundException extends HttpException {}