API docs: usage examples

Created by: slimsag

Pulling from LSIF data, show usage examples specifically in the form of "Find references" as is basically in our app today.

---

Thorsten:

The mind-blowingness of usage examples is growing by the minute. So right now I think usage examples is #1 (closed). Might be a distant #1 (closed) in 10minutes.

Usage examples is what I loved about clojuredocs.org: https://clojuredocs.org/clojure.core/map Or the old PHP docs. Or why I constantly search through https://doc.rust-lang.org/rust-by-example/ instead of using the officiall Rust docs (which are really slow and I think badly formatted). Or why I sometimes use https://learnxinyminutes.com/ to look up how to do something vs. official docs, because I know it's easier to see how something is used there.

[...] How many examples I look through? Until I find one I can copy, I guess? Say I want to find out how something common is done in a new language I'm learning, like "how to read a full file into a string". It's possible that there's 2-3 APIs involved here: file APIs, i/o APIs, string apis, etc. What I want is an example that shows me how to tie all of these together. So if I would look at something like file.open("filename") what I want in the usage examples is to see how to the opened file. I very rarely want to see 5 different invokations of file.open that shows different options. What I'm after is: how do I use this to do what I want?

---

Coury:

Another plus for usage examples. As an example of how this helps so much with onboarding to a new codebase… today I am writing some code to connect to a new table in Postgres and wanted to see the pattern in sourcegraph/sourcegraph for DB / Store. I was able to quickly generate this query and get a sense across the entire repo how this pattern is being used. Being able to 1-click from a doc reference and get to something like this would be amazing.