AI Literate Programming => Markdown?!

Literate Programming was a good and influential idea, to include "intent" for code as text
and then manage code and text together;

but didn't really get much attention, difficult tooling and management

Now when much of new code development is being quickly automated with AI Agents,
markdown is becoming a primary "source artifact", and much of code is "downstream" from it.

Trouble is that md and code files are often not connected, and even related/referenced.

And that can be changed with big benefit.

If we start using markdown for code comments, 
and adjust tools to support it (should be "easy" change),
we could actually achieve key objectives of...

Literate programming - Wikipedia

Literate programming (LP) is a programming paradigm introduced in 1984 by Donald Knuth in which a computer program is given as an explanation of how it works in a natural language, such as English, interspersed (embedded) with snippets of macros and traditional source code, from which compilable source code can be generated.^[1] The approach is used in scientific computing and in data science routinely for reproducible research and open access purposes.^[2] Literate programming tools are used by millions of programmers today.^[3]

AI Overview

Donald Knuth is most famous for creating the TeX typesetting system and the METAFONT font design system, but he also developed several specialized programming languages and paradigms: 

• WEB and CWEB: These are systems for Literate Programming, a methodology Knuth invented to allow programmers to write code interspersed with natural language explanations.
  • WEB was originally designed to work with Pascal.
  • CWEB is a later version designed for C, C++, and Java.
• MIX and MMIX: These are low-level instruction set architectures (ISAs) and their associated assembly languages.
  • MIX was used in early volumes of his landmark series, The Art of Computer Programming.
  • MMIX is a more modern, 64-bit RISC architecture that replaced MIX in newer editions.
• SOL: A symbolic language for general-purpose systems simulation.
• Literate Programming: More than a single language, this is a paradigm where the source code is treated as a work of literature, meant to be read by humans as much as executed by machines. 

Knuth also has a deep history with existing languages; he was an early expert in ALGOL 60 and FORTRAN, and his early work on the TeX system was originally written in SAIL (Stanford Artificial Intelligence Language) before being converted to Pascal using his literate programming tools.