JackStouffer is doing a lot of work lately on this check and I think we can help him too:

https://github.com/dlang/phobos/projects/1

So if you have 15 spare minutes why not help out and make Phobos's documentation better?
After all, almost everyone in the State of D survey agreed that the documentation isn't superb yet.

How can I help?
---------------

1) If you don't have Phobos setup. Fork & clone the four main repos

---
mkdir ~/dlang && cd dlang
git clone https://github.com/<username>/dmd
git clone https://github.com/<username>/druntime
git clone https://github.com/<username>/phobos
git clone https://github.com/<username>/tools
cd phobos
make -f posix.mak
---

2) Pick a module and remove it from the has_public_example blacklist in .dscanner.ini

3) Run make -f posix.mak dscanner

4) Add unittest

5) Run the tests with either

- make -f std/mymodule.test (this rebuilds Phobos before running the tests)
- ~/dlang/dmd/generated/linux/release/64/dmd -unittest -main -i -run std/mymodule.d (faster as it doesn't rebuild Phobos)
- make -f std/mymodule.publictests (this extracts the public tests into a separate file to prevent any private access problems)

6) Submit a PR

7) GOTO 2 (or celebrate)


There are also a few other blacklists here too:

https://github.com/dlang/phobos/projects

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?

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öö");