Make sure that every function in Phobos has a public example

[Seb via Digitalmars-d]

On Monday, 24 July 2017 at 10:24:48 UTC, Wolfram W. wrote:
> Hi Seb,
> thanks for the instructions. As it seems, there's actually 
> quite a lacking in public examples for some modules, and I'd 
> like to help with that. After pulling, scanning, and sifting 
> through the Phobos source however, I have some questions I'd 
> like to clarify, just to be on the safe side.
>
> Firstly, it seems that some functions already have an 
> expressive and concise undocumented unit test (Like 'exists' in 
> file.d, at line 1570; or 'urlEncode' in uri.d, at line 399). I 
> see nothing wrong with also using these unit tests as examples. 
> However, I am a bit hesitant to do so, considering these tests 
> have been here for seemingly a long time, without being marked 
> for documentation... so there's probably a reason for that?

Some tests are quite old and AFAICT documented examples weren't 
popular back then (or maybe not even supported).
There's nothing wrong with exposing these tests.

In general, public unittests should ideally
- be easy to read and understand
- don't expose implementation details
- don't use private functions (we already check this 
automatically)

Both tests that you references look short & concise to me.

A bit of background: deleteme isn't publicly documented, but used 
by so many public tests that we can't remove it anymore, but 
probably will document it in the future [1].

[1] https://github.com/dlang/phobos/pull/5400

> Secondly, especially concerning the math module--should really 
> *every* function have an example? Most notably, examples for 
> all the trigonometric functions and their relatives like 
> 'acos', 'sinh, 'tan', etc. would be nearly the same and might 
> not be that helpful, since their usage is straightforward and 
> their results are mathematically defined anyway. 
> 'assert(acos(1) == 0)' as a possible example seems a bit 
> superfluous to me.

Hehe, I wouldn't focus on std.math.
There's value in providing an example for every function (e.g. 
"intuitive" overview of the special cases (e.g. 
`tan(double.nan)`) and being able to use it as a REPL, i.e. hit 
"Edit" on the example and check your value), but I agree that 
it's definitely not as helpful as other modules.
-> Prioritize

If, at a distant point in the future, Phobos is so nicely 
documented that every module except for std.math* has public 
examples, adding examples to std.math for consistency could be a 
final step.

> Thirdly, some functions already have public examples in their 
> comments, rather than in documented unit tests (for example 
> 'getAddressInfo' in socket.d, at line 900). Since D-Scanner 
> doesn't scan any comments and also for the sake of consistency, 
> would it make sense to extract these "comment examples" and put 
> them into documented unit tests?

Commented examples should be converted to unittest examples 
whenever possible.
There have been many incidents in the past when these 
documentation examples didn't work anymore.
In the case of `getAddressInfo` it's a bit problematic, because 
the testsuite should be runnable without internet, but using sth. 
like `scope(failure)` and thus making the test "softfail" should 
work.

> Lastly, I have seen that 'dirName' in the path module has a 
> documented unit test at line 615. While D-Scanner does not 
> report the absence of an example for the function, there is no 
> example in the HTML documentation (see 
> http://dlang.org/phobos/std_path.html#dirName). Could this be a 
> bug in the HTML generator, or is there something wrong with how 
> the unit test is written?

Good catch! Imho this is a bug / missing feature in Ddoc and I 
have opened an enhancement request [2].

Note that Ddox (a replacement of builtin Ddoc) [3], parses this 
correctly:
https://dlang.org/library/std/path/dir_name.html

I'm not sure how easy / workable changing the behavior of Ddoc is 
- otherwise we might want to look into mimicking the Ddoc 
behavior at the Dscanner check. I have opened an issue there as 
well, s.t. it's not forgotten [4].

Thanks again for bringing this up!

[2] https://issues.dlang.org/show_bug.cgi?id=17678
[3] https://github.com/rejectedsoftware/ddox
[4] https://github.com/dlang-community/D-Scanner/issues/500

> Sorry for posting such a wall of text. As a (hopefully soon to 
> be) first-time contributor I want to make sure not to clog the 
> PRs with sub-par changes.

No worries, I hope my answers help. Otherwise don't hesitate to 
ask again ;-)
Also please don't be afraid to submit a "sub-par PR" - you won't 
be killed for it.
Just be careful to avoid a huge PR - multiple PRs with a small 
diff will be pulled quicker.