[META] Each artifact in the standard library should have a meaningful example

[dlangBugzillaToGithub]

andrei (@andralex) reported this on 2016-10-14T22:52:42Z

Transfered from https://issues.dlang.org/show_bug.cgi?id=16614

CC List

• greeenify
• greensunny12

Description

This is likely to stay open for a long time. Feel free to create other bugs (either at function/type level or at module level) and make this depend upon them.

Having a good example for everything there is in the standard library would vault the quality of our documentation to the next level, and is a terrific way for new members to learn.

[dlangBugzillaToGithub]

greeenify commented on 2016-10-16T18:45:31Z

Something that is related to this and also very useful is increasing the code coverage. With the new CodeCov tool (or by directly running the tests locally), it's as easy as picking a module, looking up the uncovered lines and adding tests for those. As a reward one might even find hidden bugs ;-)

[dlangBugzillaToGithub]

greeenify commented on 2016-12-27T11:12:47Z

*** Issue 16990 has been marked as a duplicate of this issue. ***

[dlangBugzillaToGithub]

greeenify commented on 2016-12-27T11:14:54Z

There's now a helper tool in dlang/tools:

https://github.com/dlang/tools/blob/master/styles/has_public_example.d

it run with e.g. dub --root=../tools/styles -c has_public_example -i std

Moreover, there's an open PR to Phobos to enable it with a blacklist:

https://github.com/dlang/phobos/pull/4998

It will introduce this as `has_public_example` Makefile target, thus from the Phobos repo one can run the following to find functions without public examples:

make -f posix.mak has_public_example

Help to reduce the blacklist is very welcome!

[dlangBugzillaToGithub]

greensunny12 commented on 2018-03-31T19:16:23Z

This is now being tracked by https://github.com/dlang/phobos/projects/1 - we are almost half-way through the remaining module blacklist :)