Comment #0 by john.michael.hall — 2017-11-30T17:04:07Z
In the reduce documentation in std.algorithm [1], there is some documentation and then unittests and then more documentation for additional functions within the headline reduce template. I believe it should be all documentation and then unittests.
This issue is not specific to reduce, but this is merely the first one I noticed it on.
[1] https://dlang.org/phobos/std_algorithm_iteration.html#reduce
Comment #1 by razvan.nitu1305 — 2017-12-04T07:56:59Z
This is not a bug, but a documented unittest. Closing as invalid.
Comment #2 by john.michael.hall — 2017-12-04T12:51:07Z
(In reply to RazvanN from comment #1)
> This is not a bug, but a documented unittest. Closing as invalid.
I'm not happy with this decision.
I understand what a documented unittest is. The problem is the ordering. Right now, for functions like reduce, it goes
1) some template-level documentation
2) unittests
3) the functions
I believe it should go
1) some template-level documentation
2) the functions
3) unittests
For other examples, I noticed it in mir-algorithm, which depends on ddoc. See
http://docs.algorithm.dlang.io/latest/mir_ndslice_topology.html#map
the actual map function where it has the returns is all the way at the end
Comment #3 by schveiguy — 2017-12-04T13:50:26Z
John Hall, it's not a bad suggestion, and definitely the documentation could be presented differently.
However, this is functionality of the documentation generator, not phobos itself. So this would have to be an enhancement to the documentation generator, which I think you understood, but maybe the title throws people off. I'm updating the title and reopening.
Comment #4 by john.michael.hall — 2017-12-04T14:21:43Z
Okay.
Comment #5 by robert.schadek — 2024-12-13T18:55:10Z