revertible random

[tarakby]

• add doc for revertibleRandom
• update doc for unsafeRandom

Changes are copied from onflow/docs#423

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
cadence-lang-docs	✅ Ready (Inspect)	Visit Preview	Nov 7, 2023 6:33pm
cadence-lang-org	✅ Ready (Inspect)	Visit Preview	Nov 7, 2023 6:33pm

[AlexHentschel]

Very nice. Added some suggestion for minor word-smithing.

[AlexHentschel]

do we need this here? We already have a very similar callout for unsafeRandom:

cadence-lang.org/versioned_docs/version-current_0.42/0.42/language/built-in-functions.mdx

Lines 39 to 42 in 107c54b

	<Callout type="info">
	`unsafeRandom()` function currently behaves the same way as `revertibleRandom()`.
	It is deprecated and will be removed in an upcoming release of Cadence.
	</Callout>

I feel this is largely duplicated and best fits within the context of unsafeRandom

Suggested change

	<Callout type="info">
	`unsafeRandom()` function currently behaves the same way as `revertibleRandom()`.
	It is deprecated and will be removed in an upcoming release of Cadence.
	</Callout>

[tarakby]

I actually duplicated it purposely. I think there is an advantage to clarify why this function is here and what's its relationship with the existing unsafeRandom. Developers used to unsafeRandom may be asking how revertible is different and this provides them with a quick answer.

I added the section for unsafeRandom afterwards as per your suggestion to keep a section for deprecated functions. I think the duplication is minor and it is temporary anyway.

[tarakby]

okay you guys win 😄 onflow/docs#439 (comment)

[AlexHentschel]

Suggested change

	`unsafeRandom` has the same interface and implementation as `revertibleRandom()` although
	it is called unsafe.
	Its implementation has been upgraded to the same implementation as `revertibleRandom()` for improved security. However, the name was retained for downwards compatibility despite it technically being no longer unsafe (see `revertibleRandom()` for details).

[turbolent]

We'll do a final sync by copying all content from the docs repo to this repo before removing the content from there. Please make changes in the docs repo, otherwise we'll end up with conflicts.

[tarakby]

cc @gregsantos

[tarakby]

@AlexHentschel thanks for the review.
I think the comments belong to the original PR onflow/docs#423. I'll open a new PR against the original docs to address your comments from here.

Update: here is the PR with your suggestions