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?