Every time this comes up, I am mystified by why very few programmers I have met are aware of the concept of Literate Programming:

http://literateprogramming.com/

as developed by Dr. Donald Knuth to create the programs TeX and METAFONT.

The big thing here is that writers need different tools than programmers --- but one thing which wasn't acknowledged for TeX was that the woven .web files documented a low level of the programs in question, one which was so low that the woven documentation wasn't really useful to most folks --- arguably, what should have happened is plain.tex and plain.mf should have been plaintex.web and plainmf.web and included the text of _The TeX Book_ and _The METAFONT Book_ respectively (perhaps one day Dr. Knuth will allow that, or take the time to do this).

The mention in this podcast of TypeSpec is interesting, but the proposed application seems a very narrow one.

A better option maybe would be a collaborative approach where it is acknowledged that code which cannot be easily explained/documented maybe needs to be re-written:

https://www.folklore.org/Inside_Macintosh.html

Just watched MIT's OCW for Introductory Python, and one of the suggestions there for debugging was describing the code to a child (or kitten, or stuffed animal) --- of course the best code is that which never needs to be written (using a library), but arguably second-best is the code which is correct and doesn't need to be debugged, so third-best would be code which is documented well enough that it may be debugged/re-written easily.

When I looked for Literate Programming tools for my current project, I didn't find anything which seemed a good fit, so resorted to asking on tex.stackexchange.com https://tex.stackexchange.com/questions/722886/how-to-write-... which allowed me to create:

https://github.com/WillAdams/gcodepreview/blob/main/literati...

which I've been using in:

https://github.com/WillAdams/gcodepreview/blob/main/gcodepre...

(which is currently being re-written in Python)

Quite simplistic, but working with the linear .tex file is way better than my previous approach of tiling 3 different files open in 3 different OpenPythonSCAD instances and using a fourth window to test the code. I'd be very interested in suggestions of other tools and resources to consider. I've been collecting LP texts at:

https://www.goodreads.com/review/list/21394355-william-adams...

(in particular, while not an LP text, Ousterhout's _A Philosophy of Software Design_ was quite striking and reading through it and then reviewing my code to apply its principles one chapter at a time helped immeasurably)

The idea that they have here of using AI to make a first automated pass at documentation and then editing it by hand seems like a lot of extra work, and likely to create the possibility of introducing some subtle misunderstanding in the text which is then difficult to ferret out.