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)
