Document where clauses.

[steveklabnik]

Closes #21859.

[rust-highfive]

r? @huonw

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

[huonw]

It might be worth mentioning that where clauses add functionality not available elsewhere, e.g.

fn foo<T>(x: T) where i32: Trait<T> {
    1i32.method(x)
}

which is the main motivation for them, rather than just syntactic nicety.

[reem]

Do we have a set style for this? The most common I've seen is:

fn bar<T, K>(x: T, y: K)
where T: Clone, K: Clone + Debug {
     ..
}

and/or

fn bar<T, K>(x: T, y: K)
where T: Clone, 
      K: Clone + Debug {
     ..
}

[mdinger]

This was also asked at http://internals.rust-lang.org/t/multiple-line-fn-and-impl-declarations/1106 but no one responded. His preference was 2 tab indentation for where.

fn bar<T, K>(x: T, y: K)
        where T: Clone, 
    K: Clone + Debug {
     ..
}

[steveklabnik]

Yeah we don't have one so I did what I'd do, and figured someone would mention it 😉

[mitchmindtree]

I've seen this pattern floating around a little also:

fn bar<T, K>(x: T, y: K)
    where
        T: Clone,
        K: Clone + Debug,
{
    ..
}

I find it nicely readable for situations where there are multiple types and many bounds, easy to refactor and plays nice with auto-indent.

[mitchmindtree]

I also recall seeing this somewhere in the std src:

fn bar<T, K>(x: T, y: K) where
    T: Clone,
    K: Clone + Debug {
    ..
}

[Nercury]

@mitchmindtree The last one looks great visually, especially if one squints :). But is just begs for { to be on the next line for such multiline case. Also, what about the result:

fn bar<T, K>(x: T, y: K) 
    -> Result<bool, String> 
where
    T: Clone,
    K: Clone + Debug 
{
    ..
}

[steveklabnik]

@huonw can you give a bigger example of that? I've never seen that before.

[huonw]

trait ConvertTo<Output> {
    fn convert(&self) -> Output;
}

impl ConvertTo<i64> for i32 {
    fn convert(&self) -> i64 { *self as i32 }
}

// can be called with T == i32
fn normal<T: ConvertTo<i64>>(x: &T) -> i64 {
    x.convert()
}

// can be called with T == i64
fn inverse<T>() -> T
        // this is using ConvertTo as if it were "ConvertFrom<i32>"
        where i32: ConvertTo<T> {
    1i32.convert()
}

[oli-obk]

another use-case and pretty explanation on stackoverflow: http://stackoverflow.com/questions/28405621/what-is-the-syntax-and-semantics-of-the-where-keyword

[steveklabnik]

Added. The only thing left is the style question.

[huonw]

Maybe this could be expanded to be specific about what is happening: where clauses allow bounds where the left-hand side is an arbitrary type, not just a plain type parameter.

[steveklabnik]

added

[steveklabnik]

@huonw r?

[huonw]

@bors r+ faf0 rollup