Josh On Design

I have greatly enjoyed the reliability of Rust so far, but a few things really annoy / mystify me. One is the type annotations. I understand that type annotations lets you say what type another type is defined in terms of. The common case is a vector of points, with something like:

MyStruct {
    list: Vec<Point>
}

However, in some apis the annotations go so deep that I don’t know what to do with them. For example in the gfx_glpyh api we have this:

use gfx_glyph::{GlyphBrushBuilder, Section};

let dejavu: &[u8] = 
    include_bytes!(“../../fonts/DejaVuSans.ttf”);
let mut glyph_brush = GlyphBrushBuilder::using_font_bytes(dejavu)
    .build(gfx_factory.clone());

It seems simple. GlyphBrushBuilder creates a GlyphBrush thing which is stored in the glyph_brush variable. But what type is that variable? Let’s see what build() returns.

pub fn build<R, F>(self, factory: F) -> GlyphBrush<‘a, R, F, H> 
   where
    R: Resources,
    F: Factory<R>, 

Ummm. What am I supposed to do with that? It has all of these open types, but the sample code I used didn’t declare any types, so what are R and F and H at runtime?

So far the fact that I don't know the full type signature of glyph_brush isn’t a problem. I can still use the variable and the compiler will tell me if I do anything wrong. But lets say I want to pass this variable to a new function like this:

fn draw_stuff(glyph_brush: GlyphBrush) {
…
}

Uh oh. This won’t compile. What should be the full type of GlyphBrush in my function? It’s not clear how to figure this out. Presumable the parameterized types of R, F, and H depend on things passed to the builder, but the docs don’t define what that is. They say

Builds a GlyphBrush using the input gfx factory

Okay, at least I have a clue that the thing passed to the build function will be part of the signature, the F part, but what about the rest?

I feel like this is a case of over-use of parameterized types, and it makes libraries hard to use if you aren’t already very familiar with the code base. Yet the point of a library is that it can do things for you without you having to fully read the source.

So my question to the Rust community is this: How do you use APIs like this? Do you have to spend a lot of time studying the examples? (Incidentally, none of the examples pass a GlyphBrush instance anywhere). Do you badger the library author until he writes more docs? What do you do?