Docs for Macro core::write are not applicable to no_std

[behnam]

Stable: https://doc.rust-lang.org/core/macro.write.html
Nightly: https://doc.rust-lang.org/nightly/core/macro.write.html

Looks like the docs are shared between core and std, because of the implementation details. But, the problem is that the examples provided for the core macro won't be working in no_std setup.

I think it's better to either add a note about this or have accurate docs that would actually work. I can't think of a quick fix, though. Any ideas?

[steveklabnik]

The only way is to write a note about the different context.

[jdhorwitz]

@steveklabnik I can take this one and work on this.

[steveklabnik]

Great! Let me know if you need anything :)

[steveklabnik]

@jdhorwitz did you ever do this? No worries if not, but If so, I'd like to close it, and if not, we should get someone else to do it, unless you're still willing :)

[MagnumOpus21]

If no one's looking at this currenty, I can contribute to this 😁 . Just need a few pointers on what needs to be accomplished.

[steveklabnik]

@MagnumOpus21 that'd be great! The docs live here:

rust/src/libcore/macros.rs

Lines 309 to 351 in 3b77203

	/// Write formatted data into a buffer.
	///
	/// This macro accepts a format string, a list of arguments, and a 'writer'. Arguments will be
	/// formatted according to the specified format string and the result will be passed to the writer.
	/// The writer may be any value with a `write_fmt` method; generally this comes from an
	/// implementation of either the [`std::fmt::Write`] or the [`std::io::Write`] trait. The macro
	/// returns whatever the `write_fmt` method returns; commonly a [`std::fmt::Result`], or an
	/// [`io::Result`].
	///
	/// See [`std::fmt`] for more information on the format string syntax.
	///
	/// [`std::fmt`]: ../std/fmt/index.html
	/// [`std::fmt::Write`]: ../std/fmt/trait.Write.html
	/// [`std::io::Write`]: ../std/io/trait.Write.html
	/// [`std::fmt::Result`]: ../std/fmt/type.Result.html
	/// [`io::Result`]: ../std/io/type.Result.html
	///
	/// # Examples
	///
	/// ```
	/// use std::io::Write;
	///
	/// let mut w = Vec::new();
	/// write!(&mut w, "test").unwrap();
	/// write!(&mut w, "formatted {}", "arguments").unwrap();
	///
	/// assert_eq!(w, b"testformatted arguments");
	/// ```
	///
	/// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects
	/// implementing either, as objects do not typically implement both. However, the module must
	/// import the traits qualified so their names do not conflict:
	///
	/// ```
	/// use std::fmt::Write as FmtWrite;
	/// use std::io::Write as IoWrite;
	///
	/// let mut s = String::new();
	/// let mut v = Vec::new();
	/// write!(&mut s, "{} {}", "abc", 123).unwrap(); // uses fmt::Write::write_fmt
	/// write!(&mut v, "s = {:?}", s).unwrap(); // uses io::Write::write_fmt
	/// assert_eq!(v, b"s = \"abc 123\"");
	/// ```

The docs need to have a note added to mention that this can be used without the standard library, and an example showing that usage. That's the high level overview, if you need more help than that, I'm happy to elaborate further!

[MagnumOpus21]

Awesome will get started @steveklabnik .

[MagnumOpus21]

@steveklabnik When I run ./x.py test src/libcore/macros.rs it fails, even before the addition of my changes to the macros file. To clarify, this is from the recent master branch and even without my changes the running the command fails. Is it ok to open a PR with that? I can add the error message here if you insist.