Issue 1:
Was: rust-lang/prev.rust-lang.org#89, from @gnzlbg, submitted January 19th 2015.

Hi,

I just tried rust for the first time. From the description of the language, I decided to try a dynamic array first, since in my head this is the most important data structure in a low level language (e.g., for cache performance). So I decided to write a small program using a Vec<T> (is this the right data-structure in rust for an array of dynamic size?). My first step was to create a vector of size elements initialized to a default value of 0. So:

I went to the Arrays, Vectors, and Slices part of the book, where:

I see how I can use the vec! macro,

I see how I can use push.

I see a link to the Vec<T> documentation, so...

I went to the Vec<T> documentation:

this looks... empty,

I see how I can use new to create an empty vector,

I guess new(size) and new(size, default_value) might work (I have a C++ background), but the compiler is helpful here and tells me that there is only new(). Ok, keep looking!

I search in the docs for Vec and arrive at:

std::vec::Vec. I wonder why I didn't land here in the first place. Here:

I see more examples using: len, iter, this page looks good, I feel I'm getting close :)

There is a section about initializing a vector with a capacity using Vec::with_capacity and why this should be preferred, this is almost what I want!

I guess Vec::with_size without success, it seems I'm not there yet, so...

I read the rest of the doc there, but it seems I'm out of luck.

I go back to Vec::resize(new_len, value), it seems that value is not documented, but I guess that it would be the default value, so...

I try:

let mut v : Vec<f64> = Vec::with_capacity(size);
v.resize(size, 0.0);

which gives a warning but works as expected.

I'm left with a very weird feeling. I'll try to explain it. What in my head should be the most used data structure in a low level language, and thus the most used data structure in rust, turned out to be barely and poorly documented. The best part of the documentation is, without doubt, the "Capacity and reallocation" where with_capacity is explained. Most of the other functions there are missing documentation. Almost none of the functions have the algorithmic/memory complexity documented. Even in those functions that are documented, some arguments aren't. I think that for vector even the growth factor (which is an implementation detail) should be included in the documentation since it can be interesting to know it in some applications (or while debugging/profiling performance). Besides improving the documentation of all these functions, the documentation of vector could be improved significantly by including different "sub sections" like "Capacity and reallocation". Those I would have found useful are: "Initialization" (how to initialize a vector: with a capacity/size, with/without default constructed elements, from slice, from pointer and length, from raw array, using the vec! macro...), "Insertion" (push, insert, resize.. and how are the elements initialized when they are created), "Deletion" (pop, selectively delete some elements based on predicate: erase_remove_if in C++, resize.. and what happens if I resize below the current size), "Memory layout" (capacity, extend capacity, shrink to fit, ...), "Iteration" (how to iterate over a vector), "Common patterns" (sort + remove duplicates, stack, queue, flat_set).

I decide to fill an issue in the rust documentation and to give rust another try in a couple of months:

nowhere in the book could I find where to fill issues,

went to the rust language on github where I read somewhere that the documentation belongs to the website

supposed that rust-www host the website and also the documentation...

Another small issue I had at the beginning was that nowhere in the introduction did I find a link or a table with the primitive data types. Most of the introduction uses i32. I guessed double and failed, but then guessed f64 and it worked. I then googled rust primitive types and got a link to the reference where all primitive types where shown. A table explaining iX for integers, fX for doubles, str for chars where X is the width of the data type would have saved me jumping around through tabs and googling.

Issue 2:
Recent changes landed that broke Rust on Mac OS 10.9 (Mavericks) and above, see #17214

The problem is that the linker is being passed an argument that works for gcc, but that clang rejects. (Mac OS moved wholesale to clang in 10.9, it appears.)

Unfortunately, this breakage wasn't caught by bors. Apparently the testing infrastructure is running an older version of Mac OS and therefor using gcc rather than clang.

To avoid surprise Mac OS breakage in the future, we should make sure to test against clang before landing PRs.

cc @brson @kballard @pnkfelix