From 3e24e958922806379f9f609e36954a489eb20831 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Tue, 25 Aug 2020 19:51:40 -0700
Subject: [PATCH] std.rand: promote normal comments to doc comments

---
 lib/std/rand.zig | 35 ++++++++++++++++++-----------------
 1 file changed, 18 insertions(+), 17 deletions(-)

diff --git a/lib/std/rand.zig b/lib/std/rand.zig
index 42726472bf..7988efffc9 100644
--- a/lib/std/rand.zig
+++ b/lib/std/rand.zig
@@ -3,21 +3,22 @@
 // This file is part of [zig](https://ziglang.org/), which is MIT licensed.
 // The MIT license requires this copyright notice to be included in all copies
 // and substantial portions of the software.
-// The engines provided here should be initialized from an external source. For now, randomBytes
-// from the crypto package is the most suitable. Be sure to use a CSPRNG when required, otherwise using
-// a normal PRNG will be faster and use substantially less stack space.
-//
-// ```
-// var buf: [8]u8 = undefined;
-// try std.crypto.randomBytes(buf[0..]);
-// const seed = mem.readIntLittle(u64, buf[0..8]);
-//
-// var r = DefaultPrng.init(seed);
-//
-// const s = r.random.int(u64);
-// ```
-//
-// TODO(tiehuis): Benchmark these against other reference implementations.
+
+//! The engines provided here should be initialized from an external source. For now, randomBytes
+//! from the crypto package is the most suitable. Be sure to use a CSPRNG when required, otherwise using
+//! a normal PRNG will be faster and use substantially less stack space.
+//!
+//! ```
+//! var buf: [8]u8 = undefined;
+//! try std.crypto.randomBytes(buf[0..]);
+//! const seed = mem.readIntLittle(u64, buf[0..8]);
+//!
+//! var r = DefaultPrng.init(seed);
+//!
+//! const s = r.random.int(u64);
+//! ```
+//!
+//! TODO(tiehuis): Benchmark these against other reference implementations.
 
 const std = @import("std.zig");
 const builtin = @import("builtin");
@@ -29,10 +30,10 @@ const math = std.math;
 const ziggurat = @import("rand/ziggurat.zig");
 const maxInt = std.math.maxInt;
 
-// When you need fast unbiased random numbers
+/// Fast unbiased random numbers.
 pub const DefaultPrng = Xoroshiro128;
 
-// When you need cryptographically secure random numbers
+/// Cryptographically secure random numbers.
 pub const DefaultCsprng = Isaac64;
 
 pub const Random = struct {