Document std::os::raw. by clarfonthey · Pull Request #46962 · rust-lang/rust

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

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

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

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

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

@@ -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?

emilyalbini · 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

Clar Charr 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 b95498fCompare 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 2cab068Compare January 29, 2018 23:16

QuietMisdreavus reviewed Jan 30, 2018
View reviewed changes

emilyalbini 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:masterFeb 6, 2018

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

		@@ -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.

Uh oh!

Uh oh!

Conversation

clarfonthey commented Dec 23, 2017

Uh oh!

rust-highfive commented Dec 23, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clarfonthey commented Dec 23, 2017

Uh oh!

alexcrichton commented Jan 4, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kennytm commented Jan 17, 2018

Uh oh!

clarfonthey commented Jan 18, 2018

Uh oh!

shepmaster commented Jan 26, 2018

Uh oh!

clarfonthey commented Jan 29, 2018

Uh oh!

clarfonthey commented Jan 29, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emilyalbini commented Feb 5, 2018

Uh oh!

QuietMisdreavus commented Feb 6, 2018

Uh oh!

bors commented Feb 6, 2018

Uh oh!

clarfonthey commented Feb 6, 2018

Uh oh!

kennytm commented Feb 6, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants