API Docs: ffi

[steveklabnik]

Part of #29329

http://doc.rust-lang.org/std/ffi/

Here's what needs to be done to close out this issue:

• the module docs are almost non-existent, and should talk about how this isn't so much FFI bindings as it is stuff useful for interop with C, which is FFI of course, but that's it. It's not a comprehensive FFI solution.
• CStr should make the comparison with str. it needs a lot of links.
• CString should make the comparison with String. It also needs a lot of links.
• FromBytesWithNulError should use the iterator style boilerplate for linking to where it came from.
• IntoStringError same
• NulError same.
• OsStr should make the str comparison, and needs a lot more elaboartion. It should look like CStr.
• OsString should make the comparison with String, and should look a lot like CString.

[seankerr]

One of the constant reminders I tell myself when working with FFI is that CStr consumes a C NULL terminated string, and that CString represents one. It would be nice if the documentation for both of these structs indicated their purpose, and contained basic FFI examples for using them.

[jethrogb]

OsString docs say

allowing a Rust string to be converted into an "OS" string with no cost.

I'm not sure if that's entirely correct and it's slightly confusing. On Windows at least you need another step through OsStrExt that is costly. Also, the reverse conversion is always costly (O(n)) to do safely.

[steveklabnik]

I am happy to mentor anyone who wants to tackle this issue.

[seankerr]

@steveklabnik I'd be happy to write the docs on these provided some guidance. When are you available for a quick doc lesson?

[steveklabnik]

@seankerr awesome! We can do it asynchronously on this issue, or synchronously if you ping me on IRC, I'm around most often during 10-6ish EST, but at other times too, and sometimes I'm in meetings.

[steveklabnik]

@seankerr I've updated the issue with some more details here