> Often an algo or structure is so much better described with an image or video- yet most comments are text based. I've written my fair share of ASCII diagrams

> Often an algo or structure is so much better described with an image or video- yet most comments are text based. I've written my fair share of ASCII diagrams. I've also smuggled links to wikis into my doc comments for e.g. cross platform abstractions for on-screen keyboards. Then I can link all the screenshots I want. Or to gifs/videos for shader effects demos. Or to a series of images and code snippets for tutorials, or ... Heck, if you're using markdown doc comments, there's no reason you couldn't embed image URLs that get expanded directly into inline images by the doc generator...