Wishlist

The wishlist is for collecting things that we want to work on but haven't done yet. It isn't a formal task list, just a place to collect ideas.

Automatically generate "src API" page

The API page (https://srclib.org/api/overview/) isn't as automated as it should be (it's generated by this file: https://sourcegraph.com/sourcegraph/srclib/.tree/docs/sources/api/overview.md). Ideally, we would be able to list out the commands we want to generate documentation from in mkdocs.yml (https://sourcegraph.com/sourcegraph.com/sourcegraph/srclib@ffb73e5fbe0590374c2434a9c9d4d9af5dd56adc/.tree/docs/mkdocs.yml), and api/overview.md would generate the correct API page with a loop.

You can see how to set up our docs here: https://sourcegraph.com/sourcegraph/srclib@master/.tree/docs/README.md

(Additionally, we use tags like "// START SomeTag OMIT" in the source code. srclib's output has enough information to get the comments we need without the above tags, because "docs" are associated with defs. We need a srclib command for getting just the relevant docs, though. Let me know if this sounds interesting to work on.)

Expose language-specific information with "src fmt"

The srclib toolchains generate lots of useful information, but it's hard to use from "srclib" itself because the information isn't language generic. The first step to solving this is exposing the information as well-formatted text from the srclib toolchains. I have preliminary work started work on this on the "interactive" branch of srclib: https://sourcegraph.com/sourcegraph.com/sourcegraph/srclib@938b27057ec1dadf437f9e7bfa1ee8d7f383a571/.tree/src/format_cmd.go

And I only added an implementation to srclib-go: https://sourcegraph.com/sourcegraph.com/sourcegraph/srclib-go@abb09df519a9176b0961d7ee2e15c4b57ac8aa0c/.tree/fmt.go

There are a couple issues with it right now:

• The definition is passed as a command line argument ("--object"), which is an issue because the operating system limits command line arguments. The defintion should be passed through stdin.
• There are only two formats defined in srclib right now, "full" and "decl". srclib-go always gives back the "decl". I don't remember what I wanted "full" to be haha, so it should probably be abandoned.
• For "decl", I don't provide any options for specifying how specific the declaration should be, so right now it defaults to fully qualified (even tho I'm passing it graph.Unqualified? There might be a bug here).
• More formats -- you should be able to pass "methods" as the format to get all of the methods of a def, or "type" for more detailed type information. Haven't completely thought this through, but the idea is that you should be able to get more detailed language-specific information using "fmt".