This is an example of documentation generated by ZigDoc, an alternative to Zig's built-in Auto Doc feature. See also examples in other modes/formats. The project being documented here (as the example) is the Zig library itself.
pubconstcan_unwind: bool = switch (builtin.cpu.arch) {
else => true,
// On x86, `RtlVirtualUnwind` does not exist. We could in theory use `RtlCaptureStackBackTrace`
// instead, but on x86, it turns out that function is just... doing FP unwinding with esp! It's
// hard to find implementation details to confirm that, but the most authoritative source I have
// is an entry in the LLVM mailing list from 2020/08/16 which contains this quote:
//
// > x86 doesn't have what most architectures would consider an "unwinder" in the sense of
// > restoring registers; there is simply a linked list of frames that participate in SEH and
// > that desire to be called for a dynamic unwind operation, so RtlCaptureStackBackTrace
// > assumes that EBP-based frames are in use and walks an EBP-based frame chain on x86 - not
// > all x86 code is written with EBP-based frames so while even though we generally build the
// > OS that way, you might always run the risk of encountering external code that uses EBP as a
// > general purpose register for which such an unwind attempt for a stack trace would fail.
//
// Regardless, it's easy to effectively confirm this hypothesis just by compiling some code with
// `-fomit-frame-pointer -OReleaseFast` and observing that `RtlCaptureStackBackTrace` returns an
// empty trace when it's called in such an application. Note that without `-OReleaseFast` or
// similar, LLVM seems reluctant to ever clobber ebp, so you'll get a trace returned which just
// contains all of the kernel32/ntdll frames but none of your own. Don't be deceived---this is
// just coincidental!
//
// Anyway, the point is, the only stack walking primitive on x86-windows is FP unwinding. We
// *could* ask Microsoft to do that for us with `RtlCaptureStackBackTrace`... but better to just
// use our existing FP unwinder in `std.debug`!
.x86 => false,
}
