This function can be auto-documented from its name and the names and types of its arguments alone. No ML required - simple pattern matching and LUTs will do. But then again, do you really need a detailed documentation in such case?
Where a documentation would actually be helpful are cases like this:
A format commonly found in the FORTRAN code of numeric libraries. If the author(s) didn't document this, an AI wouldn't stand a chance to know what it does.
PCHFE is Piecewise Cubic-Hermite Function Evaluation of course [1] and the parameters aren't exactly self-explanatory either...
Guessing !!
N,X, and F are probably related to NE,XE, and FE
"E" means "error"? Maybe.
IERR is an error flag. Idiomatic fortran there.
Each of those variables will be defined later on, in the code. at least with a type (not required, but it is not 1960 anymore). In that declaration is where some comments would be.
REAL*8 N ! Radius of the body in radians
Point being that fortran is not hopelessly opaque. A subroutine declaration is backed up with some more information.
(now if "implicit none" is not a requirement, then this all you get)
Love seeing some hard core numeric code. Precise and compact. No pointers, nothing sophisticated. Do loops, if statements, subroutine calls.
> In that declaration is where some comments would be.
Admittedly, I haven't read a lot of Fortran code, but I have yet to see anybody who includes such comments. It wouldn't be so bad except also:
a) the only code I see in Fortran is numerics code, therefore written by mathematicians or other people who seem to believe that using more than one letter to describe a term is an admission of weakness
b) people write function names as if it costs $1000 per extra character
c) there often doesn't seem to be any introductory resources to the concepts that are being implemented that might let me discover what cryptic one-letter variable names might actually refer to
> In that declaration is where some comments would be.
Here's the declaration of the parameters:
INTEGER N, INCFD, NE, IERR
REAL X(*), F(INCFD,*), D(INCFD,*), XE(*), FE(*)
LOGICAL SKIP
Sorry, but no comments to be found :)
> NE,XE, and FE "E" means "error"? Maybe.
Wrong guess - "E" means "Evaluation" as in "to be evaluated" in this case. It's also not clear which are inputs and outputs and primitive data types give no indication at all about constraints and use-case.
> IERR is an error flag. Idiomatic fortran there.
Now that's true, but idiomatic cases that are well documented and don't benefit from AI documentation. Simple pattern matching will do.
The point I was trying to make wasn't really about any specific programming language either. The point is rather that documentation requires translating implementation to intent and purpose.
If you have a system that's capable of translating a program into purpose, constraints, and usage example(s) expressed in plain natural language; you have created a system to end all programming languages, because the inverse transform would be possible as well...
