On Friday, 18 July 2014 at 19:00:56 UTC, Walter Bright wrote:
On 7/18/2014 10:59 AM, Brad Anderson wrote:
What do you think?
I'd leaven that proposal with the observation that functions
are likely to be lexically sorted by name. Hence, like
functions should lexicographically be adjacent to each other.
"setExtension" and "withExtension" will be widely separated,
and a user looking for such a function will likely see only one
of them and not be aware of the other, which may be a better
fit for him.
I really don't see the lexicographic sort order as a big priority
here. We have cross referencing to show related functions already
and that does a much better job. The only time lexicographic
ordering comes into play is with the current naive jump list
generation which does a terrible job because it lexicographically
sorts everything in the module regardless of scope so things like
enum values are scattered throughout the list. ddox does better
but still the handwritten category jump lists are much, much
better and don't rely automatic sorting.
Note that Microsoft often adds the suffix "Ex" when creating a
new version of an API function. It works well because the new
and old will be sorted right next to each other. I'm not
suggesting that these ranges add that particular suffix, just
pointing out what others do.
The most obvious suffix would be "Lazy" but I think most of us
agree we don't want that. When I'm using the Windows API I always
have to look up if I should be using the regular or the Ex
version and it's not always obvious until you've read a
surprising amount on the respective MSDN pages. I seem to recall
there are now some "ExEx" functions too. I'm not really a fan but
it is an option.
