
CodeTour for Visual Studio Code - cxr
https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour
======
lostintangent
Thanks for posting this! I’m the author of CodeTour, and would love to hear if
folks had any questions/feedback.

~~~
cxr
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.

~~~
sqs
I love the idea of showing a file summary in the tree based on the file
comment. Do you have the code or scheme you sketched out around? Would you
mind sharing it here or emailing it to me? I’m the cofounder of Sourcegraph
and would love to add this feature in today or tomorrow.

~~~
cxr
I never implemented this, but here's a transcription of my journal entries:

[https://www.colbyrussell.com/2020/05/10/index-and-
location-t...](https://www.colbyrussell.com/2020/05/10/index-and-location-
tags-for-documentation-generators.html)

