On Wed, Jul 05, 2017 at 05:07:14PM +0000, Jolly James via Digitalmars-d-learn
wrote:
> On Wednesday, 5 July 2017 at 16:55:43 UTC, bachmeier wrote:
> > On Wednesday, 5 July 2017 at 16:04:16 UTC, Jolly James wrote:
> >
> > > Here in D everything looks like climbing mount everest. When you
> > > ask how to use D's containers you are recommended to use dynamic
> > > arrays instead. When you look at the docs for std.algorithm, e.g.
> > > the .remove section, you get bombed with things like
> > > 'SwapStrategy.unstable', asserts and tuples, but you aren't told
> > > how to simply remove 1 specific element.
> >
> > If you feel that there is a problem with the docs, you should file a
> > bug: https://dlang.org/bugstats.php
> >
> > The documentation is still not perfect, but the only way to improve
> > it is to file bugs when you see something that needs fixing.
>
> unfortunately, it's not that the docs would be wrong or something that
> can be easily corrected. Nope, the docs do everything right, they show
> you what the existing things do. But what they don't do is how to get
> stuff done. imho some additional, useful guides would be nice.
No, that's a sign that the docs are not good enough. Describing what
existing things do is only the bare minimum of documentation. *Good*
documentation should also tell you what you can use it for, and give
examples of how to do it, preferably examples that address the most
common use cases first, and then, if necessary, a discussion of more
details later.
The very first example in the docs for std.algorithm.mutation.remove is
not suitable as a first example, because it already throws something
unexpected in your face, i.e., that remove() doesn't change the incoming
range directly. It should have shown the *correct* way of removing an
element as a first example, i.e.:
a = a.remove(1);
And *then* talk about the details later.
Here's my fix for this:
https://github.com/dlang/phobos/pull/5548
In the future, please do file a bug for these kinds of documentation
issues. D needs *good* documentation, not just bare-minimum
documentation.
T
--
Long, long ago, the ancient Chinese invented a device that lets them see
through walls. It was called the "window".
