Check out this talk by one of the developers from the core team. It was enlightening the first time I watched it.
The idea of only documenting tested types might be very robust in the sense that it’ll never document something that doesn’t work, but it defies one of the most fundamental paradigms in Julia, Multiple Dispatch
As a brief example, I might want to write a function that prints a matrix in a fancy way (maybe formats it as a markdown table). The best practice in Julia is to define fancy_print(m::AbstractMatrix) and use m within the function in a way that is compatible with any matrix object that is a sub-type of AbstractMatrix. If I do this right, then anyone can go ahead and use it as follows.
import LinearAlgebra: UpperTriangular
mat = [1 4 7; 2 5 8; 3 6 9]
upper_tri_mat = UpperTriangular(mat)
fancy_print(mat) # would work
fancy_print(upper_tri_mat) #would work
If appropriate, julia could even produce different machine code for the two different invocations (this is called method specialization)
I might try to test my function with a few matrix types, but I can’t really test with all of them. One of the most elegant things about Julia is that a it allows someone else to define their own matrix type and use it with my fancy_print function, and it’d work right out of the box.
Reminder that you can’t have variables of type
AbstractMatrixdirectly. All variables are of concrete types. Abstract types only define a hierarchy of types (and by convention an implicit common “interface”)
Yeah forgive me about that heuristic thing, it is a very different idea not about documentation at all.