Earlier quoted context omitted.
Something I've considered on and off is that our current way of writing code is insufficient, I'd really like to have an editor/IDE that had "layers" so that I could attach code related comments in one layer and intent/documentation in another layer - throw in the ability to hide/show layers at will and you'd have a much more flexible way of documenting code than we currently have.
It was possible do it with literate programming for ages. Combine it with emacs, mmm-mode and, say, auctex - and you'll get your IDE.
It really slows you down though (good thing?) when trying to dump your ideas into code, especially if you end up writing exploratory code that you later delete (I do this a lot).
I think literate code could be really great however for refactors. Once you've figured out the correct implementation and have the time & hopefully budget to revisit your fast code. Maybe it won't feel like the chore of straight up documentation, and more like the enjoyment of polishing your art.