Sorry, that wording was too vague. In reality, there are a few situations I’d class under “examining an API” as I was thinking of it. It’s probably better described as “reading the source as a non-contributor.” Some examples where I often do this on github rather than locally:
- looking at existing implementations of a crate’s trait that I want to implement on my own types
- evaluating a few competing crates for a task (looking at implementation details of competing solutions is useful but I’m still just browsing and the docs may not tell the whole story)
- seeing if a bug I’m hitting could be fixed easily enough to onboard as a contributor and submit a quick PR
- answering a question I have about the output of a function but where the docs aren’t clear
- I’m sure there are others but I can’t think of them right now and this seems like a decently motivated list to me
When I’m browsing source to find examples of usage, it’s usually because the crate doesn’t have sufficiently rich examples in its docs (or any at all). While rust has a significantly better docs culture than most other ecosystems I work in, there’s sometimes no substitute for seeing how a crate author uses their own API. Tests are a common place that I’ll look, for example. One could perhaps make the argument that if I’m going to this extent to understand a crate, I should just clone it.
It’s already pretty accepted that a reasonable experience of writing Rust includes tool support. Perhaps the general form of this question is how much tool support should be needed for Rust code to be easily read.
Related: are there perhaps tools that would make it easier for me to do this “parachute reading” in my own editor? Maybe the process of cloning and opening a given crate’s source could be automatic enough that the low friction of a browser+GitHub wouldn’t be worth it.
I buy that we’ll have significantly fewer files per directory in the brave new world, actually. Still not an incredibly strong argument in my mind, but it definitely makes sense.