From 9601ac698ced021892cea8a6984b2746044c412e Mon Sep 17 00:00:00 2001
From: LALITH0110 <lalith.kothuru@gmail.com>
Date: Sat, 1 Aug 2026 12:13:11 -0500
Subject: [PATCH] docs: move fillRandomBytes example to a separate file

Moves the `fillRandomBytes` dartdoc example into
`example/webcrypto/random/fill_random_bytes.dart` and references it with
`{@example ...}`, so the example is covered by `dart analyze` and
`dart format` instead of living inside a doc comment.

The example code is unchanged from what the documentation already showed.
`avoid_print` is suppressed for the file because the example prints its
result, matching how the docs demonstrate it.

Towards #283
---
 .../webcrypto/random/fill_random_bytes.dart   | 34 +++++++++++++++++++
 lib/src/webcrypto/webcrypto.random.dart       | 17 +---------
 2 files changed, 35 insertions(+), 16 deletions(-)
 create mode 100644 example/webcrypto/random/fill_random_bytes.dart

diff --git a/example/webcrypto/random/fill_random_bytes.dart b/example/webcrypto/random/fill_random_bytes.dart
new file mode 100644
index 00000000..2f0f8cda
--- /dev/null
+++ b/example/webcrypto/random/fill_random_bytes.dart
@@ -0,0 +1,34 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// ignore_for_file: avoid_print
+
+// #region example
+import 'dart:convert' show base64;
+import 'dart:typed_data' show Uint8List;
+
+import 'package:webcrypto/webcrypto.dart';
+
+void main() {
+  // Allocate a byte array of 64 bytes.
+  final bytes = Uint8List(64);
+
+  // Fill with random bytes.
+  fillRandomBytes(bytes);
+
+  // Print base64 encoded random bytes.
+  print(base64.encode(bytes));
+}
+
+// #endregion
diff --git a/lib/src/webcrypto/webcrypto.random.dart b/lib/src/webcrypto/webcrypto.random.dart
index 199a7cea..ec01f269 100644
--- a/lib/src/webcrypto/webcrypto.random.dart
+++ b/lib/src/webcrypto/webcrypto.random.dart
@@ -20,22 +20,7 @@ part of 'webcrypto.dart';
 /// calls to obtain more random bytes.
 ///
 /// **Example**
-/// ```dart
-/// import 'dart:convert' show base64;
-/// import 'dart:typed_data' show Uint8List;
-/// import 'package:webcrypto/webcrypto.dart';
-///
-/// void main() {
-///   // Allocate a byte array of 64 bytes.
-///   final bytes = Uint8List(64);
-///
-///   // Fill with random bytes.
-///   fillRandomBytes(bytes);
-///
-///   // Print base64 encoded random bytes.
-///   print(base64.encode(bytes));
-/// }
-/// ```
+/// {@example /example/webcrypto/random/fill_random_bytes.dart#example}
 void fillRandomBytes(
   TypedData destination,
   // Note: Uint8List and friends all implement TypedData, but dartdoc has a bug