Sneak peek: API documentation generated for all your code

UPDATE Nov 10, 2022: Sourcegraph has de-prioritized work on this feature at this time and it has not graduated beyond experimental status. If your team is interested in this functionality, please reach out.

At Sourcegraph, we have a small team working hard on a new experimental feature: API docs.

In order to build awesome code search we've built a global graph of code that has a deep, semantic understanding of the underlying code—which we represent as LSIF code intelligence data. Using Sourcegraph's LSIF code intelligence data, we can analyze your code and generate API documentation for all of it. We've started with Go code and intend to expand to more languages as we develop this feature.

*API docs generated for the Go encoding/json package*

Vision

If you develop in Go, Rust, or Zig you're probably familiar with some sites that try to do this like pkg.go.dev, docs.rs, etc. The benefit of Sourcegraph's API docs over these will in the future be:

• Surfacing usage examples from open source code.
• Providing a single tool that works across all code, using LSIF data to provide an experience tailored towards your languages of choice.
• Giving an amazing navigation and search experience.

Try it (experimental)

Today, it's still in its very early stages—and only a few months into development. But you can try it out on Go code today:

• Explore encoding/json code
• Explore Go net/http code
• Explore Sourcegraph backend code

Want to try it out on your own Go repositories? Tweet @sourcegraph with your GitHub repository name and we'll set it up for you, or follow our documentation.

On by default, for everyone

The most important announcement here is that API docs is now an on-by-default experiment for everyone! You can begin trying it out on Sourcegraph.com as well as your own Sourcegraph instance.

*Use the API docs button on any repository page to access API docs* *Once you click it, you'll be greeted with information about how to get started*

Understands the types of symbols, and uses iconography to communicate

API docs is built on code intelligence data, so it has a deep semantic understanding of symbols, their type information, whether they're deprecated, a function, variable, interface, etc., and the UI now communicates this information using icons

A deep understanding of code

We're paying attention to the small details, and really tailoring API docs to each language.

At Sourcegraph, we use primarily Go and TypeScript—so we're starting by building an experience that Go developers will love, then we'll expand to more languages and build an experience that is really tailored to, and makes sense in the context of, the individual language.

One way we've enabled this is by allowing LSIF language indexers to emit data in the way they see fit. Sourcegraph merely renders it, indexes it, and adds a nice navigation experience.

Direct feedback

API docs is still very early in development, so we're making it as easy as possible to give feedback. In fact, we're making it possible to email feedback directly to the lead engineer (that's me) [email protected]—I'm eager to hear what you think!

We've also made it possible to submit feedback on the API docs pages themselves,and you can also send feedback to us via Twitter @sourcegraph.

*Use the feedback widget on API docs pages, or directly email feedback to us!*

About the author

Stephen Gutekanst is one of Sourcegraph's earliest engineers, and has authored many parts of Sourcegraph including the src CLI, monitoring architecture, managed instances, and editor extensions to name a few. Stephen has worked with most of Sourcegraph's largest customers, and enjoys solving the most critical and technically challenging issues users face in our effort to bring world-class developer tools to everyone. Outside of Sourcegraph, Stephen researches and develops search engine and video game technology.

Special thanks to Rebecca Dodd and Erica Lindberg for their help with the content of this article, and Jean du Plessis and the rest of the team for their assistance and feedback on API docs.