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.
- 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:
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.
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.
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@example.com—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.
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.