chore: require safety doc comment for unsafe instead of //@safety

[asterite]

Description

Problem

Experimental: Nico requested having //@safety before the unsafe block for readability reasons. In the past I suggested using doc comments, so this is what I tried here.

Summary

The requirement is now that the unsafe block has a doc comment that starts with "Safety:" (ignoring case) before it. The doc comment can be exactly before the unsafe expression, or it can be in the statement that holds the unsafe block. I think this gives a bit more flexibility so that the safety comment isn't nested inside other expressions, leading to less readable comments and code.

For example, all of these are valid:

/// Safety: test
unsafe { 1 }

/// Safety: test
let x = unsafe { 1 };

/// Safety: test
call(unsafe { 1 });

Additional Context

Documentation

Check one:

• No documentation needed.
• Documentation included in this PR.
• [For Experimental Features] Documentation to be submitted in a separate PR.

PR Checklist

• I have tested the changes locally.
• I have formatted the changes with Prettier and/or cargo fmt on default settings.

[github-actions]

Execution Report

Program	Execution Time	%
sha256_regression	0.053s	-2%
regression_4709	0.001s	0%
ram_blowup_regression	0.572s	-1%
rollup-root	0.104s	-1%
rollup-block-merge	0.105s	0%
rollup-base-public	1.220s	-2%
rollup-base-private	0.465s	0%
private-kernel-tail	0.021s	0%
private-kernel-reset	0.347s	0%
private-kernel-inner	0.079s	2%

[github-actions]

Compilation Report

Program	Compilation Time	%
sha256_regression	1.266s	-3%
regression_4709	0.770s	-2%
ram_blowup_regression	17.960s	-1%
rollup-root	3.640s	-3%
rollup-block-merge	3.790s	4%
rollup-base-public	35.500s	-2%
rollup-base-private	12.600s	6%
private-kernel-tail	1.009s	-2%
private-kernel-reset	8.766s	4%
private-kernel-inner	2.524s	15%

[github-actions]

Compilation Memory Report

Program	Peak Memory
keccak256	78.11M
workspace	123.89M
regression_4709	422.96M
ram_blowup_regression	1.58G
rollup-base-public	4.11G
rollup-base-private	1.20G
private-kernel-tail	207.17M
private-kernel-reset	730.59M
private-kernel-inner	294.40M

[github-actions]

Execution Memory Report

Program	Peak Memory
keccak256	74.65M
workspace	123.92M
regression_4709	315.98M
ram_blowup_regression	512.41M
rollup-base-public	480.66M
rollup-base-private	326.51M
private-kernel-tail	181.02M
private-kernel-reset	249.69M
private-kernel-inner	209.86M

[github-actions]

🚀 Deployed on https://677fd5257480dc04e9cc7be9--noir-docs.netlify.app

[TomAFrench]

Much nicer!

[github-actions]

FYI @noir-lang/developerrelations on Noir doc changes.

[benesjan]

I am getting a few warnings in my PR in which it's not clear to me why they are triggered:

Typically it does not recognize this comment as valid.

To reproduce:

1. check out https://github.com/AztecProtocol/aztec-packages/blob/3e094bc69fe31bffab2ced72cd155bc4ab435b6d/noir-projects/noir-contracts/contracts/nft_contract/src/types/nft_note.nr#L54
2. go to noir-projects/noir-contracts
3. and compile with nargo compile

There is a ton of unrelated warnings so please search for "Safety:" in the terminal.
There should be 8 false warnings.

This is my nargo version:

% nargo --version
nargo version = 1.0.0-beta.1
noirc version = 1.0.0-beta.1+56ed6e16b975f91a
(git version hash: 56ed6e16b975f91a, is dirty: false)

[asterite]

@benesjan Hi! The comment on top of unsafe should be /// (triple slash). I hope this fixes the issue for you.

[benesjan]

@asterite That was indeed it. My bad. Thanks 🙏