Document std::os::raw. #46962

clarfonthey · 2017-12-23T02:45:00Z

This adds a brief explanation to each type and its definition according to C. This also helps clarify that the definitions of the types, as described by rustdoc, are not necessarily the same from platform to platform.

rust-highfive · 2017-12-23T02:45:05Z

r? @Kimundi

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

kennytm · 2017-12-23T06:52:21Z

src/libstd/os/raw/mod.rs

+/// and `*mut c_void` is equivalent to C's `void*`. That said, this is
+/// *not* the same as C's `void` return type, which is Rust's `()` type.
+///
+/// [pointer]: ../primitive.pointer.html


Broken link. Needs two ../ I guess.

[01:21:17] std/os/raw/index.html:66: broken link - std/os/primitive.pointer.html [01:21:17] std/os/raw/enum.c_void.html:56: broken link - std/os/primitive.pointer.html [01:21:26] thread 'main' panicked at 'found some broken links', /checkout/src/tools/linkchecker/main.rs:49:8

I double-checked every link but this one. ><

retep998 · 2017-12-23T07:50:43Z

src/libstd/os/raw/char.md

+
+[C's `char` type] is completely unlike [Rust's `char` type]; while Rust's type represents a unicode scalar value, C's `char` type is just an ordinary integer. In practice, this type will always be either [`i8`] or [`u8`], but you're technically not supposed to rely on this behaviour, as the standard only defines a char as being at least eight bits long.
+
+C chars are most commonly used to make C strings. Unlike Rust, where the length of a string is included alongside the string, C strings mark the end of a string with a zero. See [`CStr`] for more information.


C strings mark the end of a string with a zero

This is slightly misleading as someone might think it means 0 the character, not the literal integer value 0.

Would clarifying "the character '\0' " be sufficient?

retep998 · 2017-12-23T07:51:24Z

src/libstd/os/raw/long.md

@@ -0,0 +1,8 @@
+Equivalent to C's `signed long` (`long`) type.
+
+This type will usually be [`i64`], but is sometimes [`i32`] \(i.e. [`isize`]\) on 32-bit systems. Technically, the standard only requires that it be at least 32 bits, or at least the size of an [`int`].


Also note that it is equivalent to i32 even on 64bit Windows.

I was not aware of this; I'll remove the remarks about isize and usize in these docs.

clarfonthey · 2017-12-23T22:30:18Z

Made revisions per comments

alexcrichton · 2018-01-04T16:10:27Z

r? @QuietMisdreavus

QuietMisdreavus · 2018-01-05T17:12:31Z

src/libstd/os/raw/schar.md

@@ -0,0 +1,6 @@
+Equivalent to C's `signed char` type.
+
+This type will almost always be [`i8`], but its size is technically equal to the size of a C [`char`], which isn't very clear-cut.


The use of "isn't very clear-cut" throughout the number docs feels awkward. Is there any guidance we can paraphrase here? If not, i'd rather we use a phrase like "which is left under-specified" to make it feel marginally less wishy-washy.

Fair; I was trying to avoid duplicating the docs too much, although it's mostly wishy-washy because C's definitions are incredibly wishy-washy.

I'll probably replace it with "which does not have a strict definition like Rust does" or something a bit more eloquent.

I don't see how C doesn't have a strict definition of size of signed char 😄. In C a char's size is defined to be 1 byte, always (although 1 byte is not defined to be 8 bits) (C11 §6.5.3.4/4).

Unless Rust is going to support non-8-bit-byte system, a signed char is always an i8.

kennytm · 2018-01-17T10:59:43Z

Hi @clarcharr, just checking if this PR is still actively worked on. Could you rephrase the sentence in #46962 (review)? Thanks!

clarfonthey · 2018-01-18T22:48:12Z

@kennytm will do in a bit!

shepmaster · 2018-01-26T17:46:30Z

Ping from triage, @clarcharr ! We haven't heard from you in a week; will you still be able to make the most recent set of changes?

clarfonthey · 2018-01-29T22:54:53Z

@shepmaster + @kennytm + @QuietMisdreavus my laptop was out of commission for a bit and I'm working on rewording things right now.

clarfonthey · 2018-01-29T23:14:57Z

I've pushed the latest version; let me know if things are okay!

QuietMisdreavus · 2018-01-30T21:35:43Z

src/libstd/os/raw/uint.md

@@ -0,0 +1,7 @@
+Equivalent to C's `unsigned int` type.
+
+This type will almost always be [`u16`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as an [`int`]; some systems define it as a [`u16`], for example.


Is that first u16 supposed to be a u32?

pietroalbini · 2018-02-05T09:54:23Z

Ping from triage @QuietMisdreavus!

QuietMisdreavus · 2018-02-06T17:53:16Z

I was still waiting on one last change, but it was small enough that i put it in myself. (Sorry @clarcharr! >_>)

@bors r+

bors · 2018-02-06T17:53:18Z

📌 Commit fefd5e9 has been approved by QuietMisdreavus

clarfonthey · 2018-02-06T18:03:53Z

@QuietMisdreavus I actually think I have the commit on my machine but I forgot to push ><

kennytm · 2018-02-06T19:17:03Z

@bors rollup

…eavus Document std::os::raw. This adds a brief explanation to each type and its definition according to C. This also helps clarify that the definitions of the types, as described by rustdoc, are not necessarily the same from platform to platform.

Rollup of 7 pull requests - Successful merges: #46962, #47986, #48012, #48013, #48026, #48031, #48036 - Failed merges:

rust-highfive assigned Kimundi Dec 23, 2017

frewsxcv added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label Dec 23, 2017

kennytm reviewed Dec 23, 2017

View reviewed changes

retep998 reviewed Dec 23, 2017

View reviewed changes

kennytm added the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Dec 23, 2017

kennytm added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Dec 24, 2017

rust-highfive assigned QuietMisdreavus and unassigned Kimundi Jan 4, 2018

QuietMisdreavus reviewed Jan 5, 2018

View reviewed changes

carols10cents added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 9, 2018

clarfonthey added 2 commits January 29, 2018 17:44

Document std::os::raw.

1a04353

Revisions suggested in comments

853fa58

clarfonthey force-pushed the os_raw_docs branch from 7137420 to b95498f Compare January 29, 2018 23:14

Reworded to avoid fuzziness, mention ! in c_void docs.

2cab068

clarfonthey force-pushed the os_raw_docs branch from b95498f to 2cab068 Compare January 29, 2018 23:16

QuietMisdreavus reviewed Jan 30, 2018

View reviewed changes

pietroalbini added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Feb 5, 2018

fix docs link

fefd5e9

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 6, 2018

kennytm mentioned this pull request Feb 6, 2018

Rollup of 7 pull requests #48040

Merged

bors added a commit that referenced this pull request Feb 6, 2018

Auto merge of #48040 - kennytm:rollup, r=kennytm

bd98fe0

Rollup of 7 pull requests - Successful merges: #46962, #47986, #48012, #48013, #48026, #48031, #48036 - Failed merges:

bors merged commit fefd5e9 into rust-lang:master Feb 6, 2018

clarfonthey deleted the os_raw_docs branch April 15, 2018 20:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document std::os::raw. #46962

Document std::os::raw. #46962

clarfonthey commented Dec 23, 2017

rust-highfive commented Dec 23, 2017

kennytm Dec 23, 2017

clarfonthey Dec 23, 2017

retep998 Dec 23, 2017

clarfonthey Dec 23, 2017

retep998 Dec 23, 2017

clarfonthey Dec 23, 2017

clarfonthey commented Dec 23, 2017

alexcrichton commented Jan 4, 2018

QuietMisdreavus Jan 5, 2018

clarfonthey Jan 5, 2018

kennytm Jan 5, 2018

kennytm commented Jan 17, 2018

clarfonthey commented Jan 18, 2018

shepmaster commented Jan 26, 2018

clarfonthey commented Jan 29, 2018

clarfonthey commented Jan 29, 2018

QuietMisdreavus Jan 30, 2018

clarfonthey Jan 30, 2018

pietroalbini commented Feb 5, 2018

QuietMisdreavus commented Feb 6, 2018

bors commented Feb 6, 2018

clarfonthey commented Feb 6, 2018

kennytm commented Feb 6, 2018


		[C's `char` type] is completely unlike [Rust's `char` type]; while Rust's type represents a unicode scalar value, C's `char` type is just an ordinary integer. In practice, this type will always be either [`i8`] or [`u8`], but you're technically not supposed to rely on this behaviour, as the standard only defines a char as being at least eight bits long.

		C chars are most commonly used to make C strings. Unlike Rust, where the length of a string is included alongside the string, C strings mark the end of a string with a zero. See [`CStr`] for more information.

		@@ -0,0 +1,8 @@
		Equivalent to C's `signed long` (`long`) type.

		This type will usually be [`i64`], but is sometimes [`i32`] \(i.e. [`isize`]\) on 32-bit systems. Technically, the standard only requires that it be at least 32 bits, or at least the size of an [`int`].

		@@ -0,0 +1,6 @@
		Equivalent to C's `signed char` type.

		This type will almost always be [`i8`], but its size is technically equal to the size of a C [`char`], which isn't very clear-cut.

		@@ -0,0 +1,7 @@
		Equivalent to C's `unsigned int` type.

		This type will almost always be [`u16`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as an [`int`]; some systems define it as a [`u16`], for example.

Document std::os::raw. #46962

Document std::os::raw. #46962

Conversation

clarfonthey commented Dec 23, 2017

rust-highfive commented Dec 23, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

clarfonthey commented Dec 23, 2017

alexcrichton commented Jan 4, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kennytm commented Jan 17, 2018

clarfonthey commented Jan 18, 2018

shepmaster commented Jan 26, 2018

clarfonthey commented Jan 29, 2018

clarfonthey commented Jan 29, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pietroalbini commented Feb 5, 2018

QuietMisdreavus commented Feb 6, 2018

bors commented Feb 6, 2018

clarfonthey commented Feb 6, 2018

kennytm commented Feb 6, 2018