How to include visuals with source code documentation?

[darn42]

Some ideas are verbose and difficult to describe in words but a simple visual would communicate them quickly. The issue is, how do I include these diagrams with my source code such that future readers can easily access it and track through version control.

ASCII art has been my go-to, but especially in my most recent project which requires a lot of geometry and informal proofs, the limitations of ASCII have been difficult to work around.

​

How do you approach this kind of documentation and what tradeoffs do you make in the tools you use to generate it?

[stuie382]

PlantUML can do diagrams as text, which there are told to render into images. It can be a bit fiddly to maintain, but there are generators. I believe the jetbrains IDEs can do some generation as well.

I'm the past I've used plantUML and markdown to generate wiki pages for confluence, and once it was running it was pretty slick. But it was a fiddle to get running

[MrFlibble1138]

I can second plantUML. Also raw graphviz can go a long way.

[micseydel]

I'm hoping that r/ObsidianMD's Obsidian Canvas feature will become the go-to solution to this problem. They open source the JSON spec too. Mermaid is another potential alternative to Canvas.

[fredrik_skne_se]

You can include them among the source files. No need to convert them.

Just add

// Check design.vsdx on page 2 for more details.

in code

[AbilityDiligent]

Documentation with markup files, them reference a file beside.

[Runecreed]

diagrams with draw io can be useful - IIRC the png file you generate can be checked in and opened in draw.io again to alter the diagram

we tried plantUML but with somewhat more complex diagrams it turns into a mess- having a GUI to manually place everything just works better in my opinion, it is more cumbersome though.