Making Phobos's documentation better

[Seb]

On Tuesday, 20 March 2018 at 16:13:23 UTC, WebFreak001 wrote:
> On Tuesday, 20 March 2018 at 15:19:14 UTC, Seb wrote:
>> JackStouffer is doing a lot of work lately on this check and I 
>> think we can help him too:
>>
>> [...]
>
> hm but adding examples to some symbols just doesn't make sense, 
> for example `translate` in std.string: `translate` has no 
> example, but the symbol directly below it (`makeTrans`) has an 
> example documenting both, why would you add an example just for 
> `translate` here?

tl;dr: because of e.g. single page per symbol documentation like 
ddox (or adrdox) and consistency/automated checking.
Example: https://dlang.org/library/std/string/translate.html

Duplication can be avoided with `/// ditto`.

---

translate is a bad example, because it's an old symbol from D1 
times and I think it would never have been added to Phobos 
nowadays as it heavily depends on the GC by design and it's 
super-hard to use it in `@nogc` (that applies for most of 
std.string FWIW).

Also it has six overloads doing almost the same thing, which 
makes it rather hard to grasp for newcomers.
A modern translate would probably be more generic, e.g. use an 
OutputRange instead of a buffer, allow any kind of translation 
table to me passed and probably not couple removal into this 
function.

makeTrans is a similar legacy symbols and would nowadays accept 
an Allocator optionally, probably return something hashmap-like 
(instead of a GC-allocated string) and maybe even return 
something RefCounted.

Also since 2.079, there's substitute which can handle many cases 
of translate with one API:

"foobar".substitute("foo", "föö");