Documentation shows prototype of a function which is different from actual usage syntax

[kornelski]

http://doc.rust-lang.org/std/mem/fn.size_of.html

Displays size_of as:

pub fn size_of<T>() -> uint

which I've tried to use as:

std::mem::size_of<T>();

but to my surprise it didn't work. For reasons I don't quite understand the compiler accepts std::mem::size_of::<T>() (with extra ::).

I bet there's a very good reason why the syntax is like that, but it's non-obvious.

I wish the documentation was very clear about this (e.g. contained usage example or a note explaining the syntax).

[glfharris]

There's an example in the guide a the moment that is similar let input_num = from_str::<uint>("5"); in the guessing game section. And a bit on random numbers rand::random::<int>(); documented here http://doc.rust-lang.org/std/rand/fn.random.html. So it seems to be a consistent thing.

[Gankra]

Yes this is simply how you explicitly specify the type for a generic function call. I believe it's like that to resolve a parsing ambiguity. What shows in rustdoc is how the function is declared, not how it's used. I agree that this is confusing, though. But as @glfharris notes, this is at very least demonstrated in the guide.

@steveklabnik, any thoughts on if we should do more to address this?

[kornelski]

I didn't mean single out that one page from docs. I think all places where this tricky syntax is used need to be clearer; every page in docs relying on this should include a note or an example showing that usage syntax is different than what the prototype suggests.

To me the syntax with :: is unexpected, because it's different than prototype's syntax and different from similar analogous C++ syntax.

It's great that it's explained in the guide, but I didn't remember that detail.

I've googled for the function I wanted and got stuck with compiler complaining about nonsense:

error: T is a structure name, but this expression uses it like a function name

This error is confusing to me (I'm a rust noob):

• I am trying to use the type as part of function's name, so it seems the compiler is rejecting exactly what I'm trying to achieve
• <T>() looks even more like using a type as a function name, so I'm completely lost.

[arielb1]

@pornel

The compiler reads you expression as ((std::mem::size_of) < (T)) > (()), which doesn't work.

[steveklabnik]

I think that simply having examples of usage allevates this issue, so I'm giving it a close.