spir wrote: > These are imo essential documentation needs unfulfilled. > 1. at import place, does not tell the reader which symbols > are actually used
Two things: a) Why does it really matter at all? The specific functions won't change the fact that you depend on the module. b) Even if you grant that, what are the odds that such documentation would stay up to date as you remove the use of functions? > 2. at use place, does not tell the reader where a given symbol is imported from That introduces an unnecessary dependency on module implementation details (unnecessary in the strictest sense - it compiles fine without it!) If you want to determine that, you can consult the documentation or the compiler. > For instance, I commonly use this scheme: [snip std.file] I do that too in a lot of cases, where the module name is meaningful and not redundant. Same for things like std.base64.encode, though the new release makes the module namespace redundant... Anyway, in some cases it gives good information. But what about std.variant.Variant? Or std.json.toJSON? You're just repeating yourself, and if you want to know where it is from, you can check the imports and/or the documentation to easily confirm it: http://dpldocs.info/Variant Listing the name over and over again, and having to seek and change it over and over again when other modules make a small change, just adds a lot of work for no benefit. Besides, if you want docs on the item, you have to look it up anyway. > Maybe it's only me (and a few other martian programmers) expecting > code to > be commonly clearer... You're assuming your way is, in fact, objectively clearer.
