Sneak peek: API documentation generated for all your code

Stephen Gutekanst

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.

Sourcegraph's new API docs 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:

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.

The new API Docs button on repository pages
Use the API docs button on any repository page to access API docs
The new welcome prompt describing how to use 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 structured tree of symbols with type information to navigate a Go package
A structured tree of symbols with type information to navigate a Go package's documentation

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.

Browser URL bar showing a URL and hash designed specifically for the Go language
The Go LSIF indexer chooses to display URL hashes in a way that makes sense specifically for Go, with a `Receiver.Method` format
Hovering over symbols and showing Sourcegraph's deep semantic understanding of type information
Soon it will be possible to search and filter using Sourcegraph's deep semantic understanding of type information

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.

The new feedback widget with various emojis
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.

Get Cody, the AI coding assistant

Cody makes it easy to write, fix, and maintain code.