On Wednesday, 14 December 2016 at 22:55:26 UTC, Andrei
Alexandrescu wrote:
Made a pass through the document integrating a lot of feedback
and fleshing the proposal better:
https://github.com/andralex/DIPs/blob/155ff59984b26749af7830aeb172d3af2dae8cd7/DIPs/DIP1005.md
https://github.com/dlang/DIPs/pull/51/files
Andrei
I'd also mention that the advantage of this feature is for the
human reader (and not just ddoc generators) as you can instantly
tell where all the symbols are located which a function uses. It
could save a lot of time for the reader when analyzing a function.
For example, if we have a function like the following:
ubyte[] readSomeBytes ( )
{
return read(1024);
}
It's a non-trivial exercise for the reader to understand where
the `read` symbol is coming from. It usually involves looking up
the import list at the top of the module which is typically very
long and contains unrelated imports as the DIP mentions.
Sometimes you can use a symbol lookup shortcut in your editor,
but with a name like `read` you'll likely get a dozen modules
listed in the pop-up and you still couldn't immediately tell
which one of the symbols this `read` call refers to. Someone will
mention IDEs, but remember when you're looking at the code in
another environment (say reviewing code on Github) you may not
have quick point & click functionality to find the symbol
declaration. That's another win for this DIP.
