Commit Graph

102 Commits

Author SHA1 Message Date
Matthias Krüger
02491259c2
Rollup merge of #129645 - beetrees:fix-float-docs, r=tgross35
Fix typos in floating-point primitive type docs

Fixes a few typos. Also reflows the text of a couple of paragraphs in the source code to the standard line width to make the source easier to read (will have no effect on the rendered documentation).
2024-08-27 18:59:29 +02:00
beetrees
d0548359b5
Reflow a couple of paragraphs in floating-point primitive docs 2024-08-27 05:26:28 +01:00
beetrees
969f9702da
Fix typos in floating-point primitive type docs 2024-08-27 05:25:34 +01:00
Ralf Jung
53d4544628 move per-target NaN info into a table 2024-08-26 17:20:40 +02:00
Ralf Jung
fe2975076f float types: document NaN bit pattern guarantees 2024-08-26 17:20:40 +02:00
Trevor Gross
8e2ca0c9d5 Add a disclaimer about x86 f128 math functions
Due to a LLVM bug, `f128` math functions link successfully but LLVM
chooses the wrong symbols (`long double` symbols rather than those for
binary128).

Since this is a notable problem that may surprise a number of users, add
a note about it.

Link: https://github.com/llvm/llvm-project/issues/44744
2024-08-01 15:38:53 -04:00
León Orell Valerian Liehr
ab9e0a72ef
Rollup merge of #125043 - RalfJung:ref-type-safety-invariant, r=scottmcm
reference type safety invariant docs: clarification

The old text could have been read as saying that you can call a function if these requirements are upheld, which is definitely not true as they are an underapproximation of the actual safety invariant.

I removed the part about functions relaxing the requirements via their documentation... this seems incoherent with saying that it may actually be unsound to ever temporarily violate the requirement. Furthermore, a function *cannot* just relax this for its return value, that would in general be unsound. And the part about "unsafe code in a safe function may assume these invariants are ensured of arguments passed by the caller" also interacts with relaxing things: clearly, if the invariant has been relaxed, unsafe code cannot rely on it any more. There may be a place to give general guidance on what kinds of function contracts can exist, but the reference type is definitely not the right place to write that down.

I also took a clarification from https://github.com/rust-lang/rust/pull/121965 that is orthogonal to the rest of that PR.

Cc ```@joshlf``` ```@scottmcm```
2024-05-22 23:41:11 +02:00
Ralf Jung
7c76eec30f reference type safety invariant docs: clarification 2024-05-12 10:03:53 +02:00
Joshua Liebow-Feeser
15df3d78e4
References must also be non-null 2024-05-11 12:08:19 -07:00
Joshua Liebow-Feeser
1cefaa7432
Relax slice safety requirements
Per https://github.com/rust-lang/rust/pull/116677#issuecomment-1945495786, the language as written promises too much. This PR relaxes the language to be consistent with current semantics. If and when #117945 is implemented, we can revert to the old language.
2024-05-11 11:50:20 -07:00
Guillaume Gomez
4eedf7385b
Rollup merge of #124750 - ultrabear:ultrabear_softfloatdoc, r=workingjubilee
Document That `f16` And `f128` Hardware Support is Limited (v2)

This PR is identical to #123892, which was approved and merged but then removed from master by a force-push due to a [CI bug](https://rust-lang.zulipchat.com/#narrow/stream/242791-t-infra/topic/ci.20broken.3F).

r? ghost

Original PR description:

---

This adds a small paragraph to the recently added f16 and f128 types explaining that hardware support may be limited, and that performance may suffer as a result of that.

I mainly wrote this because I felt it may be useful to express in some form; as a launchpoint for readers of the documentation if they have issues with performance.

I tried to word the documentation in a way that doesn't create false assumptions (that f16/f128 is too slow to use, for instance), removing the software implementation part could mislead people to thinking that f16/f128 is only available on some platforms, not all, so I believe it is important to keep in.\
"not all *major* platforms" is specifically said so as to not be redundant, because not all platforms implement many things, but the average rustacean is probably going to be using x86_64 or aarch64 derived ISA's, which is who this documentation is targeted towards.

I'm not sure of the best way to word the documentation, or if it should even be added, but I feel like it may be useful to have (potentially in a reworded way, I'm not very confident in the current wording and cannot decide if that is because it is too vague to be useful or too specific to be generally correct).
2024-05-05 16:42:48 +02:00
Alex H
5aa2f9a208
Make f128 docs mention lack of any normal platform support
Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>

Update library/core/src/primitive_docs.rs

Remove orphaned doc link and clean up grammar a bit

Update library/core/src/primitive_docs.rs
2024-05-04 14:51:55 -07:00
Alex H
3ef25288a4
Make f16 and f128 docs clearer on platform support
Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>

Update library/core/src/primitive_docs.rs

Rewrite f16 and f128 hw support comments to match PR feedback

I wrote RISC-V allcaps in all cases, and wrote amd64 lowercase in all
cases, im not sure if either is the more correct way for either
platform, thats just how I normally write them, if theres a precedent
elsewhere it should probably be changed to match though.

Update library/core/src/primitive_docs.rs

Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>

Update library/core/src/primitive_docs.rs

Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>

Update library/core/src/primitive_docs.rs
2024-05-04 14:51:35 -07:00
Alex H
e30ad6ff2c
Tgross feedback tweaks
Co-authored-by: Trevor Gross <t.gross35@gmail.com>

Update library/core/src/primitive_docs.rs

Co-authored-by: Trevor Gross <t.gross35@gmail.com>

Update library/core/src/primitive_docs.rs
2024-05-04 14:51:13 -07:00
Waffle Maybe
e18b6e819e
fixup links in never type docs
Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>
2024-05-02 06:04:16 +02:00
Waffle Lapkin
e2eb053bba Slightly reformat !'s docs after applying github suggestions 2024-05-02 04:19:43 +02:00
Waffle Maybe
3a40e838bf
Apply suggestions from code review
Co-authored-by: Kevin Reid <kpreid@switchb.org>
Co-authored-by: Herman Skogseth <herman.skogseth@me.com>
Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>
2024-05-02 04:13:57 +02:00
Waffle Maybe
b73bfd26e4
Apply suggestions from code review
Co-authored-by: Jubilee <46493976+workingjubilee@users.noreply.github.com>
2024-04-27 00:47:23 +02:00
Waffle Lapkin
23b67de151 Document never type fallback in !'s docs 2024-04-26 20:49:34 +02:00
Chris Denton
89117f85e3
Use fake libc in core test 2024-04-15 17:50:49 +00:00
ultrabear
3fd8c6432d
doc note that f16 and f128 hardware support is limited 2024-04-13 04:15:10 -07:00
Trevor Gross
311ad55c32 Add primitive documentation for f16 and f128 2024-04-10 13:50:27 -04:00
Markus Reiter
14ed426eec
Use generic NonZero everywhere in core. 2024-02-22 15:17:33 +01:00
Matthias Krüger
3d7d709925
Rollup merge of #120880 - RalfJung:vtable-fnptr-partialeq, r=cuviper
add note on comparing vtables / function pointers

Fixes https://github.com/rust-lang/rust/issues/99388
Fixes https://github.com/rust-lang/rust/issues/117047
2024-02-11 23:19:09 +01:00
Ralf Jung
1383657a46 add note on comparing vtables / function pointers 2024-02-10 14:58:37 +01:00
Oli Scherer
a59a1e7c2c Remove some invalid cfg(doc) code 2024-02-05 10:17:35 +00:00
Dylan DPC
8017ea4016
Rollup merge of #116677 - joshlf:patch-11, r=RalfJung
References refer to allocated objects

Partially addresses https://github.com/rust-lang/unsafe-code-guidelines/issues/465
2024-01-29 12:56:51 +00:00
Joshua Liebow-Feeser
b867c7c707
Update primitive_docs.rs 2024-01-27 08:47:14 -08:00
Joshua Liebow-Feeser
c2c6e33335
Update primitive_docs.rs 2024-01-25 06:59:51 -08:00
Matthias Krüger
48ba7217c6
Rollup merge of #119907 - asquared31415:fn_trait_docs, r=Nilstrieb
Update `fn()` trait implementation docs

Fixes #119903

This was FCP'd and approved for the 1.70.0 release, this is just a docs update to match that change.
2024-01-19 08:15:04 +01:00
asquared31415
46ad13136c update fn pointer trait impl docs 2024-01-12 22:09:38 +00:00
asquared31415
51afc0922c
fix typo in fn() docs 2024-01-12 15:51:18 -05:00
Miguel Ojeda
dd928c8f75 Primitive docs: fix confusing Send in &T's list
The two lists in this document describe what traits are implemented on
references when their underlying `T` also implements them. However,
while it is true that `T: Send + Sync` implies `&T: Send` (which is
what the sentence is trying to explain), it is confusing to have `Send`
in the list because `T: Send` is not needed for that. In particular,
the "also require" part may be interpreted as "both `T: Send` and
`T: Sync` are required".

Instead, move `Send` back to where it was before commit 7a477869b7
("Makes docs for references a little less confusing"), i.e. to the `&mut`
list (where no extra nota is needed, i.e. it fits naturally) and move the
`Sync` definition/note to the bottom as something independent.

Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
2023-12-29 22:26:23 +01:00
Ralf Jung
c7e3b3f84c do not allow ABI mismatches inside repr(C) types 2023-12-17 09:34:25 +01:00
bors
e299752868 Auto merge of #118032 - RalfJung:char-u32, r=Mark-Simulacrum
guarantee that char and u32 are ABI-compatible

In https://github.com/rust-lang/rust/pull/116894 we added a guarantee that `char` has the same alignment as `u32`, but there is still one axis where these types could differ: function call ABI. So let's nail that down as well: in a function signature, `char` and `u32` are completely equivalent.

This is a new stable guarantee, so it will need t-lang approval.
2023-12-11 04:13:19 +00:00
Maybe Waffle
1a3c5c40ca rustdoc: Remove space from fake-variadic fn ptr impls
before: `for fn (T₁, T₂, …, Tₙ) -> Ret`
after: `for fn(T₁, T₂, …, Tₙ) -> Ret`
2023-11-26 15:01:42 +00:00
Ralf Jung
b4f3f2aeac guarantee that char and u32 are ABI-compatible 2023-11-18 08:24:02 +01:00
Matthias Krüger
1cabedc256
Rollup merge of #115476 - RalfJung:abi-compat-docs, r=Mark-Simulacrum
document ABI compatibility

I don't think we have any central place where we document our ABI compatibility rules, so let's create one. The `fn()` pointer type seems like a good place since ABI questions can only become relevant when invoking a function through a function pointer.

This will likely need T-lang FCP.
2023-11-17 08:10:26 +01:00
Ralf Jung
8f03a55566 linking in general has more pitfalls than just call ABI 2023-11-17 08:02:28 +01:00
Ralf Jung
52d22eaa23 clarify ABI compatibility of fn ptr types and ptr types
and add an and
2023-11-11 13:36:02 +01:00
Ralf Jung
044d05769b add 'import functions' to the list of situations where ABI compatibility comes up 2023-11-10 20:33:19 +01:00
Matthias Krüger
1ee5e12710
Rollup merge of #117534 - RalfJung:str, r=Mark-Simulacrum
clarify that the str invariant is a safety, not validity, invariant

Updates these docs to match https://github.com/rust-lang/reference/pull/792
2023-11-04 21:38:29 +01:00
Matthias Krüger
805a56fc28
Rollup merge of #116894 - joshlf:patch-12, r=RalfJung
Guarantee that `char` has the same size and alignment as `u32`
2023-11-04 21:38:28 +01:00
Ralf Jung
0550ba5f77 avoid acronyms when we don't really need them 2023-11-04 12:24:09 +01:00
Ralf Jung
281d8cc4ae document ABI compatibility 2023-11-04 11:22:17 +01:00
Joshua Liebow-Feeser
1a0309afb6
Update primitive_docs.rs 2023-11-03 06:41:23 -07:00
Ralf Jung
57f570bb33 clarify that the str invariant is a safety, not validity, invariant 2023-11-03 07:23:24 +01:00
Oli Scherer
4512f211ae Accept less invalid Rust in rustdoc 2023-10-31 13:58:03 +00:00
Joshua Liebow-Feeser
c278bc1f81
Update library/core/src/primitive_docs.rs
Co-authored-by: scottmcm <scottmcm@users.noreply.github.com>
2023-10-25 08:26:07 -07:00
Joshua Liebow-Feeser
3fea7cc7da
Guarantee that char has the same size and alignment as u32 2023-10-18 09:14:31 -07:00