On Monday, 14 December 2015 at 20:25:17 UTC, bachmeier wrote:
On Monday, 14 December 2015 at 19:38:26 UTC, Jack Stouffer
wrote:
If you're trying to use Phobos without knowing what template
constraints and ranges are, you're going to have a bad time.
D is doomed if new users have to understand template
constraints and ranges to use the standard library. To be
honest, I don't know why you should have to understand either
of those to test if two arrays have the same length.
I agree. I was just debugging one of the phobos tests on
Android/ARM and I couldn't make head nor tails of what the
function was supposed to do, after a couple minutes' skim:
http://dlang.org/phobos/std_algorithm_sorting.html#nextEvenPermutation
That may be an obscure function that requires technical knowledge
to use, but any function should first have a layman's
description, in case the layman might want to use it. Template
constraints and ranges in the Phobos docs definitely suffer from
this. Saying that users should always read the relevant sections
of Ali's book first is not going to work, as most users don't
RTFM.
The problem is that documentation for an OSS project,
particularly breaking it down for someone new to the language, is
a classic tragedy of the commons: work that nobody benefits
personally from and isn't very interesting to do, so I understand
why it's the way it is.
I wonder if a possible solution is to automatically generate some
doc comments and links to glossary/tutorials from the template
constraints, in addition to the formatting changes others have
suggested.
