What about Image Insertion plugin for Visual Studio?

If you’re using a different IDE and either it doesn’t support embedded images or you don’t have time to extend it, then what about putting a link to an image in the comments, while the image would reside somewhere in the repository?

If you are not an ASCII artist, you can use doxygen as documentation tool together with dot/graphviz integrated to it.

This allows for writing textual description of graphs and rendering them in documentation.

For instance, this description:

digraph finite_state_machine {
    rankdir=LR;
    size="8,5"
    node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
    node [shape = circle];
    LR_0 -> LR_2 [ label = "SS(B)" ];
    LR_0 -> LR_1 [ label = "SS(S)" ];
    LR_1 -> LR_3 [ label = "S($end)" ];
    LR_2 -> LR_6 [ label = "SS(b)" ];
    LR_2 -> LR_5 [ label = "SS(a)" ];
    LR_2 -> LR_4 [ label = "S(A)" ];
    LR_5 -> LR_7 [ label = "S(b)" ];
    LR_5 -> LR_5 [ label = "S(a)" ];
    LR_6 -> LR_6 [ label = "S(b)" ];
    LR_6 -> LR_5 [ label = "S(a)" ];
    LR_7 -> LR_8 [ label = "S(b)" ];
    LR_7 -> LR_5 [ label = "S(a)" ];
    LR_8 -> LR_6 [ label = "S(b)" ];
    LR_8 -> LR_5 [ label = "S(a)" ];
}

renders as:

You could try the emacs artist mode. It would do ascii art rather than images per se, so it may or may not be what you’re looking for. In particular, if your IDE doesn’t do fixed-width fonts, it wouldn’t be useful. Being plain text, it would play very nicely with version control.

Here’s a screencast of artist mode being used, so you can get an idea if you’re interested or not.

To start up artist mode in emacs, do Alt-x, type artist-mode, and hit return. The middle mouse button brings up the menu. The keybindings for cut and paste aren’t the normal windows ones by default, but you can turn on CUA mode to change that.

What do people think? Would anyone pay for this? I would.

ZOMG, I fit in a similar category as you and would love such a feature directly in the IDE.

For now I just tend to do lots of ASCII “art” like this:

// ******************************************************
// *v3            |e5          v4*           |e6      v6*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p1        *
// *              |            e1*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *cen           |p0          v0*           |        v5*
// *--------------~--------------************************
// *e4            |              *           |e7        *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p2        *
// *              |            e2*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *v2            |e3          v1*           |e8      v7*
// ******************************************************

The main value I find is seeing the variable names corresponding to the visual diagram, especially when we’re using complex traversals of meshes and such for new mesh algorithms. This doxygen graph-generating trick shown in one of the answers is super cool — I should try that more.

There are so many things that are easier to communicate visually as well, not necessarily even using graphs. Example:

… or this (comparison of my algorithm I’m calling “hook subdivision” to standard CC subdivision as used by Pixar):

It would give the code so much context to just see what these operations do and how they differ inside the code because some things are just best shown visually. Pictures really can capture a thousand words.

So it would be totally dreamy to me to have an IDE that let me see code and images side-by-side, allowing me to embed images into the source code.

Especially when we’re inventing new algorithms, it’s hard to find a good way to describe them very accurately (from a technical perspective, not exactly user perspective) without going into their algorithmic steps since there’s nothing to really compare them to directly. These kinds of before and after images tend to totally show what you can expect from the algorithm right away.

Another thing I dream about is a visual debugger that lets me program it so that I can make some of my data types output an image into the debugger, e.g., to see the results visually as I’m stepping through code and making sure the algorithms I’m trying to invent are working correctly at every step and matching up how I drew it up on paper. For example, make my mesh data structure output a rendered image in the debugger watch window — ideal if I could even rotate the view and such right then and there.

Also when working in very large-scale codebases (tens of millions of LOC) written by loose teams with like a thousand plugins, sometimes it can be a nightmare just to figure out how to execute the code we’re looking at for some obscure, rarely-used plugin from the UI. It would be so awesome in those cases if the code could embed a miniature screenshot showing how to actually invoke that code from the user interface (might be prone to get out of date from time to time, but usually UIs aren’t so unstable across versions as to render former screenshots useless).

Would anyone pay for this? I would.

So anyway, yeah, totally! I want that!!!

Doxygen allows you to insert images in comments like this:

  /*! Here is a snapshot of my new application:
   *  image html application.jpg
   */

Unfortunately it seems like no IDEs will display these images inline, but I suspect it wouldn’t be too hard to write a VSCode extension to do it for example.

I did also find one VSCode extension that already support this with a different syntax commentimg. This does it via a hover:

VSCode are adding a feature that allows inline images – “code inset” – but it does not appear to be ready quite yet.

Here is a screenshot from the sample extension (which I couldn’t actually find – presumably hasn’t been released yet since the code inset API isn’t released yet)

Sounds like a use-case for Literate Programming where you could add diagrams and whatever to your documentation.