I don’t think this is documented properly, no. But packageOverrides is literally implemented as an overlay that throws away the self argument and only passes super to the defined function. And from what I’ve read overlays was intended to obsolete packageOverrides. I wish someone would update the manual where it talks about packageOverrides though.
I would really appreciate an explanation to this phenomenon as I can’t understand what are the semantics when the overlay list has 2 items “import” and “./nix-markdown-snippets.nix” and how does it cause the aforementioned infinite recursion problem.
The overlay array is an array of functions that take self: super:. By including import as the function directly, this is calling import self, and using that as part of the definition of self. import appears to call builtins.toPath on its argument, which in turn calls toString (and then interprets the results as an absolute path). toString can accept a set, if the set contains a __toString = self: … attribute.
So, as a result, if an entry in the overlays attribute is the function import, it tries to evaluate import self, where self is a set, and the import ends up forcing the __toString attribute, and in order to determine if there is in fact a __toString attribute it needs to evaluate the overlays, which ends up recursing right back to the import.
It didn’t occur to me to treat import as just a normal function that accepts self and super arguments, although that is precisely the would-be type for the args of the overlays array, makes sense now, thanks (again) for that!