On Wednesday, 12 February 2020 at 10:39:06 UTC, mark wrote:
Library Reference Documentation
The Library Reference documentation seems to be a mixed bag.
Often I've found a good overview at the start, but then few or
no examples in the docs for classes and methods (see e.g.,
https://dlang.org/phobos/std_zip.html#.ZipArchive).
I don't find the presentation of the member properties and
methods very easy to read, but the worst aspect is the lack of
examples.
It's a bug if something isn't properly documented, whatever the
flaw may be. It's gotten a lot better in the time that I've been
using D, but there are still a few rough spots.
My strategy has been to ask for an example in the forum. I then
click "Improve this page" in the upper right corner and it's a
simple process to create a PR with the example added. Most of the
documentation PRs I've created have been merged within a fwe
hours. If you don't want to do that, you can create an issue in
Bugzilla, with a detailed explanation of what you were doing and
what the documentation should show instead.
It would be nice for this to already be done, and while it's
generally good by the standards of programming languages, there
are still some weak spots. Anyone can help fix them. In some
cases when I've reported missing documentation, there actually
*was* documentation but it wasn't getting added to the website
for some reason. Nobody will know until it's pointed out. And
nobody's going to shout at you for filing too many documentation
bugs or creating too many PRs to fix documentation bugs.
