CodeTour for Visual Studio Code

I frequently come across projects where it's not at all obvious in which directories you should look to find the "meat" of the code, or what rationale the maintainers have for splitting up the code in a certain way. I wish that CodeTour (or any other tools trying to do similar things) would as much as possible work with existing conventions instead of create new bespoke file formats.

Netscape/mozilla.org's old Bonsai tool (or LXR?) had a really cool thing where when viewing a directory of source files, it would peek at the first few lines of a file, and if it contained what looked like a single-line comment presumably describing what the file was about, then it would put that description next to the file name in the directory listing.

A couple years ago, I sketched out some conventions for how you might use lightweight doxygen-/javadoc-/jsdoc-inspired annotations in the project README to document the source tree layout. (Some project maintainers already include rough descriptions in the README about where things live, and they're heroes, but not at all the norm.) The idea being that it should be readable as prose, but also have enough semantic richness that it could be extracted by machine.

Something like that has to be at least 10× more helpful than the way that GitHub—and tons of other web VCS frontends that came before—choose show a table where they dump the latest commit message and the last time that the file was touched, respectively, into columns 2 and 3. It's pretty surprising that Sourcegraph doesn't address this.

It would also be very nice to be able to generate a dumb HTML version of the tour. I can imagine it would be somewhat popular to create blog posts that are little more than these snapshots meant to highlight specific ideas. Nowadays when people blog, they include examples and snippets. Instead, they could embody their ideas in a small project of working code and then annotate a CodeTour-ified version that they can then whittle down (or just dump wholesale) into a blog post.