sampsonj

Oh, one more thing: I should mention that you’ll probably want to fetch documentation only after a code block has been in view for n milliseconds (like what I do in my extension). Otherwise, you risk throttling if a user scrolls very quickly through a webpage. It should only fetch documentation once the user pauses on a block.

Please post here once you have something working, or what you find if you struggle. I would be interested to see if you could get something working and would love to be wrong, as it would be nice to have something similar that does not use an LLM. It would be really cool if something more useful comes out of my experiment. I don't think you could reuse much from my codebase, but feel free to take anything from it that you want.

Some things that might be useful to know to speed you up:

1. Most code blocks on the internet are easy to find in a webpage. They generally are surrounded by `<code/>` tags. You can query for these using the method in my extension. Then you will need to filter out any code block that has a `<span/>` count <= 1, as code blocks are used to highlight arbitrary stuff on the internet and you would really just want to find the blocks of code.

2. You will need a method to identify when to generate documentation for a code block even with your implementation, as some documentation websites are one really long page. You can do this with two types of observers that I use in my codebase. One will identify when a code block is in view and the other will keep track of mutations to code blocks. You need to keep track of mutations because sites like ChatGPT continuously edit a code block while streaming a response. You want to generate documentation once it's done, as that's when the code is well formed. I have a janky example of how to do this in my extension. Claude should be able to find the code.

3. LLMs were useful for building this, but they struggled with design decisions, especially around UX. This project seems out of distribution for them. Claude probably won't suggest the right solution a lot of the time, but if you have it list out multiple options, it can usually identify which one is best.

I will probably check back here in a couple weeks if I don't hear anything from you. I would be really impressed if you can get something working in a weekend that is *not just hard coded for a specific use case, but scales well.*

I agree that parsing codebases and linking code to documentation is a solved problem. I think @ramon156's suggestion to use tree-sitter or something similar to parse an abstract syntax tree makes sense.

To clarify my earlier point, I wasn't suggesting this is impossible, just that it's not *practical* to build a universal LSP that works with every language and framework out of the box without anything local to index. I don't think an reusing an LSP would be a great fit here either, since LSPs rely on having full project context, dependencies, and type information. These aren't available when analyzing code snippets on arbitrary webpages.

Parsing was never my major concern though. It's the "map tokens to URLs" part. A universal mapping for every token to every piece of documentation on the internet is *impractical* and difficult to maintain. To achieve parity without LLMs, I'd need to write and maintain parsers for every documentation website, and that assumes documentation even exists for most tokens (which it doesn't).

I think kristopolous's suggestion of grounding the LLM with data sources that keep a serialized database of documentation from many different places makes the most sense. That way, the LLM is just extracting and presenting key information from real documentation rather than generating from scratch.

There are probably ways to make this easier. Maybe an offline job that uses LLMs to keep mappings up to date. The project could also be scoped down to a single ecosystem like Rust where documentation is centralized, though that falls apart once you try to scale beyond one language as mentioned above. Maybe I could use raw definition on GitHub combined with an LSP to generate information?

Open to other suggestions on how to bridge this gap.

Good point, thank you

Can you elaborate more. It's still early and I would love feedback

lol thank you, I was just going to respond to them. One thing I should mention too is that if it were at all practical to build without using generative AI, someone would have built something similar years ago before LLMs.

Thank you! I will look into these! Yeah, it could be useful for providing explanations of key terms in papers or something similar.

The LLM approach is simpler and more flexible since it works with every library and language out of the box.

Looking up official documentation would require shipping sophisticated parsers for each language, plus a way to map tokens to their corresponding docs. I'd also need to maintain those mappings as libraries evolve and documentation moves. Some ecosystems make this easier (Rust with docs.rs), but others would be much harder (AWS documentation, for example).

I also want explanations visible directly in hover hints rather than linking out to external docs. So even with official documentation, I'd need to extract and present the relevant content anyway.

Beyond that, the LLM approach adapts to context in ways static docs can't. It generates explanations for code within the documentation you're reading, and it works on code that doesn't compile, like snippets with stubs or incomplete examples.

It could be interesting in the future to look into doing some type of hybrid approach where an LLM goes out and searches up the documentation, that way it's a little bit more flexible. But that would also be a bit slower and more costly.