Code should generate diagrams automatically as you write it. Then you can see the complexity increase as you go, instead of looking back on a tangled mess.
I've worked with documentation auto-generators before, and the problem they have is that they can't figure out which references are relevant and which aren't. I remember auto-generating a class diagram of a Java project in the late 90's and it showed every class having a reference to the class "java.lang.String". Generators have gotten (a little) smarter with one-off heuristics like "treat the class String as if it were a primitive", but they're still way more cluttered than a knowledgeable human would ever come up with.
What we do with appmap.io is to depict only your own code and not dependencies. Also, each diagram depicts a runtime trace and not just static imports. It produces a more focused diagram, and it also clearly illuminates factors like HTTP client and server requests, and SQL, that static analysis can’t see. The data can be depicted as a dependency map, sequence diagram, detailed trace, and flame graph.
Our languages mostly do not have the syntax needed to express higher abstractions. You could create one via meta files or special comment notation perhaps, but it doesn't exist yet (outside of class diagram generators).
A big part of this problem is the "code-model gap".
> Code should generate diagrams automatically as you write it.
That's fine for some purposes, but for general discussions around many subjects (project planning, security, integration testing, etc) you won't get there from generated diagrams out of some code in an application.
