Document the unsafe keyword

[poliorcetics]

Partial fix of #34601 (just one more and it will be done 😄).

I tried to be concise and redirect as much as possible on other, longer resources, exposing only the strict necessary.

I also used SAFETY: comments to promote good documentation.

I would like a thorough review to ensure I did not introduce mistakes that would confuse people or worse, lead them to write unsound code.

@rustbot modify labels: T-doc,C-enhancement

Edit: this is now the last PR for the original issue: fixes #34601.

[rust-highfive]

r? @dtolnay

(rust_highfive has picked a reviewer for you, use r? to override)

[jyn514]

Not super experienced in unsafe, just a few ideas I had off the top of my head.

[poliorcetics]

Modified lots of things ! The biggest change is the new The different meanings of unsafe section, the others changes are mot simple fixes taken from suggestions during review, including the link to Send and Sync.

[dtolnay]

I don't know who on T-doc reviews this kind of thing but let's try this:

r? @rylev

[dtolnay]

@bors delegate=rylev

[bors]

✌️ @rylev can now approve this pull request

[rylev]

@dtolnay I'm not sure if I'm the right person since the dissolution of the docs team. Happy to do reviews though.

[poliorcetics]

@rylev I changed the wording, is it better ?

I'm still not particularly satisfied about my solution to the last point you made: here is what I wrote now but it feels heavy and forced to me, I you have anything better I'll take it !

-/// This different meanings have led to [discussion]s about the ability to make
-/// `unsafe` operations inside `unsafe fn`.
+/// As of now (Rust 1.44), this meanings become entwined when writing an
+/// `unsafe fn`: this syntax acts like an `unsafe` block around the code inside
+/// the function **and** as a signal to callers about the conditions they must
+/// met before using it.
+///
+/// Mixing this two meanings as one can be confusing and [discussion]s exist
+/// about the necessity to use `unsafe` blocks inside such functions when making
+/// `unsafe` operations.

[pickfire]

@poliorcetics What is entwined? I had to read that up, I wonder if if this would be better.

-/// This different meanings have led to [discussion]s about the ability to make
-/// `unsafe` operations inside `unsafe fn`.
+/// As of now (Rust 1.44), `unsafe fn` can act like an `unsafe` block around
+/// the code inside the function **or** a signal to callers that some conditions
+/// must be met before using it.
+///
+/// Mixing these two meanings can be confusing and [discussion]s exist to use
+/// `unsafe` blocks inside such functions when making `unsafe` operations.

about the conditions they must met before using it.

What conditions? unsafe?

[poliorcetics]

What conditions? unsafe?

I was thinking about the conditions to safely call an unsafe fn, like passing a correct pointer and the correct associated length for a function like quick_sort(int32_t *tab, size_t size).

[bors]

☔ The latest upstream changes (presumably #73265) made this pull request unmergeable. Please resolve the merge conflicts.

[Dylan-DPC-zz]

r? @steveklabnik

[steveklabnik]

Thanks for this! I have two small edits, r=me after

[poliorcetics]

@steveklabnik done, do you want me to squash ?

[Dylan-DPC-zz]

@poliorcetics better to squash

[poliorcetics]

Rebased and squashed :)

[Dylan-DPC-zz]

@bors r=steveklabnik rollup

[bors]

📌 Commit 0e610bb has been approved by steveklabnik