Make sure that every function in Phobos has a public example

[Wolfram W. via Digitalmars-d]

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?

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.

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?

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?

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.

Thanks,
  W

(PS: Line numbers refer to the current commit, 
e8ef731e48e6ca7a13ad813da1c3ea1aeae93d01)