For packages, ?PkgName will pull up the readme if there is no module docstring. So I would only include one if it is more informative than the readme. Otherwise it is annoying to lose that information. (This does not apply to Base or submodules of course).
For some packages the README.md file is quite long, essentially a manual, and it often has links to extraneous things like CI status. I would think that for REPL help you’d generally want something more minimalist that fits on a terminal in < 40 lines or so.
Of course, the issue linked above is about fixing cases that have no docstring at all. In such cases, even a couple sentences is a big improvement — it can always be expanded later.
Yes, but I have seen module docstrings written like
The main module for MyPackage.
which can be frustrating (since if they just didn’t spend the time to add that, a more informative result - the README - would appear). I agree README’s aren’t optimal, but they can be pretty good, so I just want folks to know that fallback exists so they only overwrite it if they really have something better.
Yeah, that’s great to do, that issue looks really valuable. I think the term “ecosystem modules” in the OP got me sidetracked to packages.
I’m not saying you should manually write down all the public names, I’m saying the docstring should explicitly say how the authors expect a user to interact with the module.
Again, in the case of CSV, the docstring mentions some methods and gives an example, but AFAIK nowhere in the documentation says “CSV doesn’t export any function, we recommend you call each function a qualified name e.g. CSV.read(…)”.