www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Documentation Improvement Initiative

reply Mike Parker <aldacron gmail.com> writes:
Preliminary discussions are underway for a new event to encourage 
improvements to documentation across the D ecosystem. I can't 
provide any details yet because the details aren't yet fixed. I 
don't even know for sure it's going to happen.

However, the best way to make it happen is for us to have a solid 
set of well-defined documentation tasks. Putting that together is 
going to require help from the community. All of us have 
encountered areas where improvement is needed in the spec, the 
Phobos docs, and docs for dub, vibe.d, and many other tools and 
projects around the D ecosystem. Some of it has made it into 
Bugzilla (which will be mined for material), but much of it has 
been buried in the forum archives or evaporated into the ether 
from the IRC/Discord/Slack channels.

This thread is a place to collect your documentation pain in one 
place. I'm about to publish a blog post announcing this (a few 
minutes after I hit 'Send' on this post):

http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/

As I mention there, we need you to be as specific as you can. 
What, specifically, is missing? What is unclear? What is 
incorrect? Give as much detail as you can. We want to be able to 
gather this info and define specific documentation tasks that 
anyone can step in and complete with the information provided.

Any project in the D ecosystem is fair game. So please help us 
out and tell us how D documentation can be improved for you.

If you feel the urge to wax philosophical on something you see 
here, please start a new thread and do all the philosophical 
waxing you want there. Let's keep this one focused on listing 
specific documentation issues. Do feel free to expand on any post 
here with information you think is relevant.

Thanks!
Feb 17
next sibling parent bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 This thread is a place to collect your documentation pain in 
 one place. I'm about to publish a blog post announcing this (a 
 few minutes after I hit 'Send' on this post):

 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/
This is a working link: https://dlang.org/blog/2020/02/17/news-update-swag-platforms-documentation-help-and-more/
Feb 17
prev sibling next sibling parent reply bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 As I mention there, we need you to be as specific as you can. 
 What, specifically, is missing? What is unclear? What is 
 incorrect? Give as much detail as you can. We want to be able 
 to gather this info and define specific documentation tasks 
 that anyone can step in and complete with the information 
 provided.
Sorry for this not being more specific, but we need a version of Rust's "The Cargo Book" for D: https://doc.rust-lang.org/cargo/ The reason I can't be more specific is because I don't use Dub except when doing so is trivial. We need documentation in particular on using Dub with mixed language projects. The obvious case is C and D, but one of our strengths is interoperability with basically all languages, so we should have examples showing how to use Dub with projects containing Fortran, Python, Lua, etc.
Feb 17
parent reply Panke <tobias pankrath.net> writes:
On Monday, 17 February 2020 at 12:52:09 UTC, bachmeier wrote:
 Sorry for this not being more specific, but we need a version 
 of Rust's "The Cargo Book" for D:
 https://doc.rust-lang.org/cargo/
 The reason I can't be more specific is because I don't use Dub 
 except when doing so is trivial.

 We need documentation in particular on using Dub with mixed 
 language projects. The obvious case is C and D, but one of our 
 strengths is interoperability with basically all languages, so 
 we should have examples showing how to use Dub with projects 
 containing Fortran, Python, Lua, etc.
I'd second this. Figuring out how sub packages work, how to structure a project into different interdependent sub packages, how to fetch dependencies (dub upgrade does not work recursively :() took way too long coming back to D. Generally a bit of best practice guidelines would be useful, see for example the my current question in the learn forum.
Feb 17
parent reply Martin Tschierschke <mt smartdolphin.de> writes:
On Monday, 17 February 2020 at 13:55:57 UTC, Panke wrote:
[...]
 We need documentation in particular on using Dub with mixed 
 language projects. The obvious case is C and D, but one of our 
 strengths is interoperability with basically all languages, so 
 we should have examples showing how to use Dub with projects 
 containing Fortran, Python, Lua, etc.
I'd second this. Figuring out how sub packages work, how to structure a project into different interdependent sub packages, how to fetch dependencies (dub upgrade does not work recursively :() took way too long coming back to D. Generally a bit of best practice guidelines would be useful, see for example the my current question in the learn forum.
Yes better docs for DUB! With as many - as possible - use case examples.
Feb 18
parent reply Jan =?UTF-8?B?SMO2bmln?= <hrominium gmail.com> writes:
I think there are two ways of looking at the documentation: from 
the expert's eyes and the beginner's eyes.
I can provide feedback from the latter:
It takes some time to learn how to navigate in the library 
reference. But this comes with time. (and also with my 
inpatiance, since I am the "click a lot, read in detail later" 
type of guy).
What I lacked most was Ali's book. It answered many questions 
(especially regarding ranges). So for beginners, a more detailed 
tutorial (or a more prominent link to Ali's book) would be great.
Yes, sometimes, I find something in the wiki. There are some 
tutorials and some cookbooks. However, the information is 
scattered, sometimes outdated. Scattering of the information is 
even worse if I think about random tutorials or blogs on the 
internet.
The language reference is sometimes challenging to read (again 
for beginners). They have essential examples, but if you don't 
have the experience, it is sometimes tough to utilize the 
provided information and incorporate it into your code. My 
workflow usually involves a simple feature, which I then try to 
use; however, a simple one-liner does not cover my problem. On 
the other hand, too exhaustive examples will clutter the 
documentation.

For beginners, a more used wiki with concentrated information 
would be great.
However this is a D-Community solution. (and maybe i am wrong. 
Maybe the wiki is great and I am not long enough around to read 
it threw).
Feb 18
parent bachmeier <no spam.net> writes:
On Tuesday, 18 February 2020 at 15:42:18 UTC, Jan Hönig wrote:
 For beginners, a more used wiki with concentrated information 
 would be great.
I strongly agree with this. D's website is oriented towards search, which is a good way to find information if you know what you're looking for, but that's hardly optimal for a beginner. For some reason our wiki isn't used much, so we only have ourselves to blame. Maybe part of a documentation improvement initiative is finding ways to encourage wiki contributions contribute more to the wiki. Maybe it's because people think you need special authority to post things there. Honestly, there's a lot of stuff in the learn forum that deserves to be organized and put on the wiki IMO. The important question is: What is not on the wiki that should be there?
Feb 18
prev sibling next sibling parent reply bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 This thread is a place to collect your documentation pain in 
 one place.
The documentation for cross compiling/linking using LDC isn't exactly what I'd call user friendly. It would really help to have a complete example so that someone can be up and running within five minutes. It would also be nice to have an example that avoids Dub altogether, and to the extent that examples do use Dub, they're complete and can be used by a beginner to the language (so at least brief explanations of Dub usage is explained, with links to proper documentation).
Feb 17
parent bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 15:01:32 UTC, bachmeier wrote:
 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 This thread is a place to collect your documentation pain in 
 one place.
The documentation for cross compiling/linking using LDC isn't exactly what I'd call user friendly. It would really help to have a complete example so that someone can be up and running within five minutes. It would also be nice to have an example that avoids Dub altogether, and to the extent that examples do use Dub, they're complete and can be used by a beginner to the language (so at least brief explanations of Dub usage is explained, with links to proper documentation).
Sorry, forgot the link to the page that should be improved: https://wiki.dlang.org/Cross-compiling_with_LDC
Feb 17
prev sibling next sibling parent reply bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 This thread is a place to collect your documentation pain in 
 one place.
I once tried to use std.socket: https://dlang.org/phobos/std_socket.html Although it does link to a couple of examples, they don't have any explanation, so I gave up. An example where you're up and running in five minutes using Dub would be really nice. It's pretty clear that the documentation for std.socket assumes the user has learned sockets programming in another language before coming to D. We should remove that prerequisite.
Feb 17
next sibling parent reply Andre Pany <andre s-e-a-p.de> writes:
On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:
 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 This thread is a place to collect your documentation pain in 
 one place.
I once tried to use std.socket: https://dlang.org/phobos/std_socket.html Although it does link to a couple of examples, they don't have any explanation, so I gave up. An example where you're up and running in five minutes using Dub would be really nice. It's pretty clear that the documentation for std.socket assumes the user has learned sockets programming in another language before coming to D. We should remove that prerequisite.
Adam D. Ruppe wrote a very good socket tutorial. You can find it here http://dpldocs.info/this-week-in-d/Blog.Posted_2019_11_11.html Kind regards Andre
Feb 17
parent bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 18:48:25 UTC, Andre Pany wrote:
 On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:
 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 This thread is a place to collect your documentation pain in 
 one place.
I once tried to use std.socket: https://dlang.org/phobos/std_socket.html Although it does link to a couple of examples, they don't have any explanation, so I gave up. An example where you're up and running in five minutes using Dub would be really nice. It's pretty clear that the documentation for std.socket assumes the user has learned sockets programming in another language before coming to D. We should remove that prerequisite.
Adam D. Ruppe wrote a very good socket tutorial. You can find it here http://dpldocs.info/this-week-in-d/Blog.Posted_2019_11_11.html Kind regards Andre
That looks pretty good. It would have to be incorporated into our official docs though, at least by providing a link.
Feb 17
prev sibling next sibling parent JN <666total wp.pl> writes:
On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:
 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 This thread is a place to collect your documentation pain in 
 one place.
I once tried to use std.socket: https://dlang.org/phobos/std_socket.html Although it does link to a couple of examples, they don't have any explanation, so I gave up. An example where you're up and running in five minutes using Dub would be really nice. It's pretty clear that the documentation for std.socket assumes the user has learned sockets programming in another language before coming to D. We should remove that prerequisite.
I think one of these could be incorporated as an example, either Adam's or Ali's code: https://forum.dlang.org/thread/cexeumxikeovazyotkfl forum.dlang.org I always use those when starting a new D networked project.
Feb 17
prev sibling parent Daren Scot Wilson <darenw darenscotwilson.com> writes:
On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:
 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 This thread is a place to collect your documentation pain in 
 one place.
I once tried to use std.socket: https://dlang.org/phobos/std_socket.html Although it does link to a couple of examples, they don't have any explanation, so I gave up. An example where you're up and running in five minutes using Dub would be really nice. It's pretty clear that the documentation for std.socket assumes the user has learned sockets programming in another language before coming to D. We should remove that prerequisite.
I am exactly such a person today! The last time I did anything with sockets was 15 (?) years ago, and was very basic, and only for part of one day. This week, I wanted to toss together a quickie tool to send some test data in binary over UDP to another machine. I had to forget about the "quickie" part of that. All the info I need about D and its libraries is there, but often details are hard to find if I don't already know the name of the module to look in. More examples would help. Just basic usage examples, not too basic, but enough to do something simple. Running off somewhere else to learn UDP sockets in C or Python or whatever then coming back isn't my idea of efficiency. Would-be users of D coming from science, engineering, fine arts, economics, robotics, or wherever, are likely to be interested in the good features of D but unlikely to want to learn another language to understand some feature, such as sockets. D documentation shouldn't try to explain these sorts of things from scratch, of course, but a few of the very fundamental ideas need to be shown in an example and a few words.
May 07
prev sibling next sibling parent jxel <jxel gmall.com> writes:
Literally nothing in core.stdc has documentation. Would rather 
have the documentation be there when you auto complete or 'go to 
definition' in an editor.

Same with system libraries in core.sys. What's worse there is 
that the parameter names for the functions are just 'a', 'b', 
'c', etc... Instead of the name of the actual argument.
Feb 17
prev sibling next sibling parent RazvanN <razvan.nitu1305 gmail.com> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

The elephant in the room is the DMD codebase. Examples:

1. https://dlang.org/phobos/dmd_apply.html

Empty page, with no explanation of what is the purpose of the page

2. https://dlang.org/phobos/dmd_attrib.html

Most of the documentation is non-existent, lacking or 
insufficient to understand what happend

3. https://dlang.org/phobos/dmd_expression.html

Most classes have no explanation. I would expect that each class 
would be followed by some pieces of code that highlight to what 
code the class maps

4. https://dlang.org/phobos/dmd_traits.html

It's missing documentation for the single most important function 
in the file: semanticTraits which does semantic analysis for 
`__traits()`

These are just a few examples, but the dmd codebase is full of 
such examples. In addition, now that dmd as a library is 
available, things are worse because people have no way of using 
it effectively since they cannot understand what's happening 
there. Moreover, it is impossible to attract new contributors 
when a complex piece of software is severely underdocumented.

Besides documenting this code, I think it is necessary in some 
situations to refactor the code so that we can highlight the 
documentation. For example, the traits file in dmd (link number 
4) contains a single function `semanticTraits` which has 1500 
lines of code and contains the whole traits semantic logic 
organized as if/else branches. The documentation for those 
branches will not be publicly available, so we must refactor the 
code to use separate functions. This will make the code cleaner 
and help us with documentation which is a great plus.
I gave this example because it is typical for a lot of situations 
in the dmd codebase. So not only it is a great chance to improve 
the documentation of dmd, but also to make the codebase more 
modern.
Feb 17
prev sibling next sibling parent reply Panke <tobias pankrath.net> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 If you feel the urge to wax philosophical on something you see 
 here, please start a new thread and do all the philosophical 
 waxing you want there. Let's keep this one focused on listing 
 specific documentation issues. Do feel free to expand on any 
 post here with information you think is relevant.

 Thanks!
A timeline of current language changes would be nice. What is currently deprecated and when will it be removed, what can be found under `dmd -preview=?` and when it will be part of the language or if it is just under consideration.
Feb 18
parent James Blachly <james.blachly gmail.com> writes:
On 2/18/20 10:59 AM, Panke wrote:
 A timeline of current language changes would be nice. What is currently 
 deprecated and when will it be removed, what can be found under `dmd 
 -preview=?` and when it will be part of the language or if it is just 
 under consideration.
Seconding this as CRITICAL as the language evolves
Feb 18
prev sibling next sibling parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Feb 17, 2020 at 12:16:26PM +0000, Mike Parker via Digitalmars-d wrote:
[...]
 This thread is a place to collect your documentation pain in one
 place. I'm about to publish a blog post announcing this (a few minutes
 after I hit 'Send' on this post):
 
 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/
 
 As I mention there, we need you to be as specific as you can. What,
 specifically, is missing? What is unclear? What is incorrect? Give as
 much detail as you can. We want to be able to gather this info and
 define specific documentation tasks that anyone can step in and
 complete with the information provided.
[...] std.windows.registry does not have any docs. The website doesn't even have a link for it! (And going to the page by editing the URL manually brings up a page with no docs for any symbol.) Note that the code itself *does* have docs; the problem is that the website docs are generated on Posix but all symbols in this module are under version(Windows). We seriously need to generate docs for *all* platforms, not just the one being used to generate them! (The other std.windows.* modules have the version(StdDoc) hack, but that's seriously b0rken because what's used to generate docs is different from what actually compiles, meaning any mistakes will not be caught by CI, code examples are not compile-checked, etc..) T -- People tell me that I'm skeptical, but I don't believe them.
Feb 18
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 18 February 2020 at 18:39:57 UTC, H. S. Teoh wrote:
 std.windows.registry does not have any docs.
http://dpldocs.info/locate/?searchTerm=std.windows.registry This is one of the big reasons why I decided *against* using dmd for my doc generation thing - it actually follows `version` rules which is necessary for compiling, but a bad thing for docs! So instead I did a separate parser. Join me and together we rule the Dalaxy with good documentation!
Feb 18
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Tue, Feb 18, 2020 at 07:08:56PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
 On Tuesday, 18 February 2020 at 18:39:57 UTC, H. S. Teoh wrote:
 std.windows.registry does not have any docs.
http://dpldocs.info/locate/?searchTerm=std.windows.registry This is one of the big reasons why I decided *against* using dmd for my doc generation thing - it actually follows `version` rules which is necessary for compiling, but a bad thing for docs! So instead I did a separate parser. Join me and together we rule the Dalaxy with good documentation!
Maybe we should *replace* the current docs with dpldocs... Make dpldocs the official doc system. Throw out the current half-baked stuff... T -- Without outlines, life would be pointless.
Feb 18
parent reply Les De Ridder <les lesderid.net> writes:
On Tuesday, 18 February 2020 at 20:50:19 UTC, H. S. Teoh wrote:
 On Tue, Feb 18, 2020 at 07:08:56PM +0000, Adam D. Ruppe via 
 Digitalmars-d wrote:
 On Tuesday, 18 February 2020 at 18:39:57 UTC, H. S. Teoh wrote:
 std.windows.registry does not have any docs.
http://dpldocs.info/locate/?searchTerm=std.windows.registry This is one of the big reasons why I decided *against* using dmd for my doc generation thing - it actually follows `version` rules which is necessary for compiling, but a bad thing for docs! So instead I did a separate parser. Join me and together we rule the Dalaxy with good documentation!
Maybe we should *replace* the current docs with dpldocs... Make dpldocs the official doc system. Throw out the current half-baked stuff... T
I frankly much prefer the current docs over dpldocs. While dpldocs might be technically superior, the UI is quite bad, it looks cold and cluttered to me. A large part of this can probably be fixed through CSS changes, though.
Feb 19
next sibling parent Paolo Invernizzi <paolo.invernizzi gmail.com> writes:
On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
wrote:
 On Tuesday, 18 February 2020 at 20:50:19 UTC, H. S. Teoh wrote:
 On Tue, Feb 18, 2020 at 07:08:56PM +0000, Adam D. Ruppe via 
 Digitalmars-d wrote:
 [...]
Maybe we should *replace* the current docs with dpldocs... Make dpldocs the official doc system. Throw out the current half-baked stuff... T
I frankly much prefer the current docs over dpldocs. While dpldocs might be technically superior, the UI is quite bad, it looks cold and cluttered to me. A large part of this can probably be fixed through CSS changes, though.
+1 ...
Feb 19
prev sibling next sibling parent bachmeier <no spam.net> writes:
On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
wrote:
 On Tuesday, 18 February 2020 at 20:50:19 UTC, H. S. Teoh wrote:
 On Tue, Feb 18, 2020 at 07:08:56PM +0000, Adam D. Ruppe via 
 Digitalmars-d wrote:
 On Tuesday, 18 February 2020 at 18:39:57 UTC, H. S. Teoh 
 wrote:
 std.windows.registry does not have any docs.
http://dpldocs.info/locate/?searchTerm=std.windows.registry This is one of the big reasons why I decided *against* using dmd for my doc generation thing - it actually follows `version` rules which is necessary for compiling, but a bad thing for docs! So instead I did a separate parser. Join me and together we rule the Dalaxy with good documentation!
Maybe we should *replace* the current docs with dpldocs... Make dpldocs the official doc system. Throw out the current half-baked stuff... T
I frankly much prefer the current docs over dpldocs. While dpldocs might be technically superior, the UI is quite bad, it looks cold and cluttered to me. A large part of this can probably be fixed through CSS changes, though.
I agree. It's not a problem for me, but if it's the *official* documentation generator, it needs a better design. That shouldn't take much though. These days there are tons of static site generators, so it's easy to steal a design.
Feb 19
prev sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
wrote:
 A large part of this can probably be fixed through CSS changes, 
 though.
If you send me a concept sketch or css suggestion we can talk about it. I have a somewhat long list of things that I'm not happy with, though any fix for those needs to not break the things that do work... and the problem I've had isn't so much identifying the problems as finding the solutions. So I'd prefer specific fix ideas over general "I don't like this" things.
Feb 19
next sibling parent reply bachmeier <no spam.net> writes:
On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe 
wrote:
 On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
 wrote:
 A large part of this can probably be fixed through CSS 
 changes, though.
If you send me a concept sketch or css suggestion we can talk about it. I have a somewhat long list of things that I'm not happy with, though any fix for those needs to not break the things that do work... and the problem I've had isn't so much identifying the problems as finding the solutions. So I'd prefer specific fix ideas over general "I don't like this" things.
If it's going to become the official documentation, it needs to match the existing website 100%. That's not currently the case. The other thing that immediately stands out to me when I click a random project's documentation, like this: https://hunt-database.dpldocs.info/hunt.html is that the page doesn't contain a lot of information. This https://dlang.org/phobos/std_range.html is much more approachable. Maybe that can be avoided, I don't know, but the first example doesn't bring me joy. I'm not the biggest fan of all the information on this page (comparing apples to apples now): http://dpldocs.info/experimental-docs/std.range.html I think it would be better to be able to click to expand if you want information about types. iota, for instance, is cluttered but the extra information doesn't bring much to the table. I also don't understand why the functions are listed twice.
Feb 19
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 19 February 2020 at 17:09:02 UTC, bachmeier wrote:
 The other thing that immediately stands out to me when I click 
 a random project's documentation, like this:
 https://hunt-database.dpldocs.info/hunt.html
 is that the page doesn't contain a lot of information.
That's because the author of that project wrote near-zero documentation. I can't fix that myself.
 I think it would be better to be able to click to expand if you 
 want information about types. iota, for instance, is cluttered 
 but the extra information doesn't bring much to the table.
Yeah, the members list is one of the things I'm not really happy with. I'm not sure there's any real value in separating out classes, structs, enums, etc., and I do think it shows too much there. I did just fix a bug in it so it doesn't duplicate those function prototypes (actually the technical difference was they had separate constraints, but sine that isn't visible here it looked like a total duplicate and waste) anymore. But the other worry is the information on the right. Part of this is that the documentation in the source doesn't really follow the spec. https://dlang.org/spec/ddoc.html#summary says the first thing in a ddoc comment is supposed to be a short summary. Then you put in a paragraph break and write the rest of your details. Though maybe I can just limit the size on my side though. But yeah this members list is one of the things I was never actually happy with so I'm open to any ideas to change it, potentially up to a total replacement. if you refresh this now you can see some changes: http://dpldocs.info/experimental-docs/std.range.html
 I also don't understand why the functions are listed twice.
Ddoc's limitations led to the authors writing it out by hand, but then my generator auto-generates a list and doesn't realize the hand-written list is there (and even if it did, the hand written list is frequently incomplete!). So now it has both. The ddox version on the official site does basically the same thing for the same reason: https://dlang.org/library/std/range.html ddox strips types out of its listing on the left, something I've also considered, but I find types to be really useful... My generator also has the ability to group functions into categories http://dpldocs.info/experimental-docs/arsd.nanovega.html#members but that requires a tag be added to the source and Phobos does the hand-written tables instead of tags on the functions since ddoc doesn't support tagging anyway. so bleh.
Feb 19
parent John Colvin <john.loughran.colvin gmail.com> writes:
On Wednesday, 19 February 2020 at 20:47:11 UTC, Adam D. Ruppe 
wrote:

 My generator also has the ability to group functions into 
 categories

 http://dpldocs.info/experimental-docs/arsd.nanovega.html#members

 but that requires a tag be added to the source and Phobos does 
 the hand-written tables instead of tags on the functions since 
 ddoc doesn't support tagging anyway. so bleh.
That's pretty cool
Feb 20
prev sibling next sibling parent reply Les De Ridder <les lesderid.net> writes:
On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe 
wrote:
 On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
 wrote:
 A large part of this can probably be fixed through CSS 
 changes, though.
[...] So I'd prefer specific fix ideas over general "I don't like this" things.
I don't particularly feel like bikeshedding too much about what it should look like, I'm not great at UI design. That said, I think the design of the current official docs is pretty good and fits in well with the rest of dlang.org. Some of the things that I think would help: add more padding, simplify the colour scheme, use monospaced fonts, use less bold fonts. Examples after fiddling around with the CSS for a couple minutes: Before: https://u.sicp.me/m2sMw.png After: https://u.sicp.me/ieJht.png Official docs: https://u.sicp.me/kzZTg.png (Maybe we ought to move this to a seperate thread or to IRC/Slack?)
Feb 19
parent Mike Parker <aldacron gmail.com> writes:
On Thursday, 20 February 2020 at 00:11:58 UTC, Les De Ridder 
wrote:
 On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe 
 wrote:
 On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
 wrote:
Guys, can we please keep this thread focused on specific documentation issues like I asked? I want as many issues as we can get and to be able to go through the thread without wading through lots of off topic discussion. Thanks!
Feb 19
prev sibling parent reply John Colvin <john.loughran.colvin gmail.com> writes:
On Wednesday, 19 February 2020 at 16:37:41 UTC, Adam D. Ruppe 
wrote:
 On Wednesday, 19 February 2020 at 11:15:33 UTC, Les De Ridder 
 wrote:
 A large part of this can probably be fixed through CSS 
 changes, though.
If you send me a concept sketch or css suggestion we can talk about it. I have a somewhat long list of things that I'm not happy with, though any fix for those needs to not break the things that do work... and the problem I've had isn't so much identifying the problems as finding the solutions. So I'd prefer specific fix ideas over general "I don't like this" things.
My general problem with most docs is that I actually prefer the "one big page" approach per-module. The practical relationships between functions, objects, methods and members often aren't hierarchical and it's so much easier to get an overview by scrolling through a larger page. The same reason applies to why I almost never use code-folding in an editor.
Feb 20
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Thu, Feb 20, 2020 at 10:21:25AM +0000, John Colvin via Digitalmars-d wrote:
[...]
 My general problem with most docs is that I actually prefer the "one
 big page" approach per-module. The practical relationships between
 functions, objects, methods and members often aren't hierarchical and
 it's so much easier to get an overview by scrolling through a larger
 page.
 
 The same reason applies to why I almost never use code-folding in an
 editor.
Yeah, the one-page doc is nicer because you can actually search for keywords on the page and find what you want, instead of having to click on who knows how many links just to get to the one place you already know is there. T -- Marketing: the art of convincing people to pay for what they didn't need before which you fail to deliver after.
Feb 21
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Friday, 21 February 2020 at 19:27:51 UTC, H. S. Teoh wrote:
 Yeah, the one-page doc is nicer because you can actually search 
 for keywords on the page and find what you want, instead of 
 having to click on who knows how many links just to get to the 
 one place you already know is there.
But on the other hand, external search engines do a very poor job actually getting you there. That's why my site does a bit of both: dpldocs.info/std.ascii will search for you, the module page has an overview listing of members, and you have clear URLs for outside linking. Even on the current dlang.org site, the ddox versions are more likely to pop up on outside web searches than the ddoc single page one!
Feb 21
prev sibling next sibling parent reply Mathias Lang <pro.mathias.lang gmail.com> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 Preliminary discussions are underway for a new event to 
 encourage improvements to documentation across the D ecosystem. 
 I can't provide any details yet because the details aren't yet 
 fixed. I don't even know for sure it's going to happen.

 However, the best way to make it happen is for us to have a 
 solid set of well-defined documentation tasks. Putting that 
 together is going to require help from the community. All of us 
 have encountered areas where improvement is needed in the spec, 
 the Phobos docs, and docs for dub, vibe.d, and many other tools 
 and projects around the D ecosystem. Some of it has made it 
 into Bugzilla (which will be mined for material), but much of 
 it has been buried in the forum archives or evaporated into the 
 ether from the IRC/Discord/Slack channels.

 This thread is a place to collect your documentation pain in 
 one place. I'm about to publish a blog post announcing this (a 
 few minutes after I hit 'Send' on this post):

 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/

 As I mention there, we need you to be as specific as you can. 
 What, specifically, is missing? What is unclear? What is 
 incorrect? Give as much detail as you can. We want to be able 
 to gather this info and define specific documentation tasks 
 that anyone can step in and complete with the information 
 provided.

 Any project in the D ecosystem is fair game. So please help us 
 out and tell us how D documentation can be improved for you.

 If you feel the urge to wax philosophical on something you see 
 here, please start a new thread and do all the philosophical 
 waxing you want there. Let's keep this one focused on listing 
 specific documentation issues. Do feel free to expand on any 
 post here with information you think is relevant.

 Thanks!
1. Dub documentation DUB needs much, much better documentation. Especially cookbooks (there's already some, but it is not accessible enough IMO). Example of how to structure a project (writing a library with an executable, writing a project with examples that are separate and compile, writing a client/server app or any two apps linked together, writing a project that interface with C/C++, writing a project that use some preprocessor, e.g. dtoh, etc..). Some of this documentation will *also* require fixes to Dub (e.g. https://github.com/dlang/dub/issues/1474 for anything using preprocessor). There is a feature that allows a project to provide skeleton for apps using it, it might also be useful to try to do it with a few projects. 2. DMD documentation Inexistent. Enough said. 3. C++ interfacing documentation The documentation for interfacing with C++ is ridiculously outdated (e.g. it says that operators overloads are not callable from D). I am currently rewriting it. Also, some other features are not documented. It would be helpful to have a language expert going over it and see what missing (e.g. yesterday I found out `pragma(crt_{con,de}structor)` was missing, despite being in the language since 2018-01-01). But I don't have specific example of missing features ATM. 4. Documentation history https://issues.dlang.org/show_bug.cgi?id=20588 5. More pattern documentation Some of https://github.com/zhaopuming/awesome-d could be integrated in the website, e.g. I've never heard of https://garden.dlang.io/ before! Likewise, http://p0nce.github.io/d-idioms/ provide amazing tips. One (anecdotal) example is that `enum` is over-used in the docs while `static immutable` (with initializer) should arguably be the default for people.
Feb 19
parent Andrea Fontana <nospam example.com> writes:
On Thursday, 20 February 2020 at 03:32:50 UTC, Mathias Lang wrote:
 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 [...]
1. Dub documentation I agree. Some of this documentation will *also* require fixes to Dub (e.g. https://github.com/dlang/dub/issues/1474 for anything using preprocessor). There is a feature that allows a project to provide skeleton for apps using it, it might also be useful to try to do it with a few projects. 2. DMD documentation I agree. Not only code documentation but also overview & c. It's very difficult to help with dmd development starting from nothing.
I would add a thing. Consider this: bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if (isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 && !isInfinite!Range2); It's a pretty easy example of a function template. But I guess it is quite confusing for a newcomer. Why do we need to focus documentation on function signature? Can't we replace the function signature as main piece of information with something more easier to read for a newcomer? Andrea
Feb 20
prev sibling next sibling parent Kagamin <spam here.lot> writes:
https://abload.de/img/tmpenki4.png - web 2.0 went too far.
Feb 23
prev sibling next sibling parent reply p.shkadzko <p.shkadzko gmail.com> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 Preliminary discussions are underway for a new event to 
 encourage improvements to documentation across the D ecosystem. 
 I can't provide any details yet because the details aren't yet 
 fixed. I don't even know for sure it's going to happen.

 However, the best way to make it happen is for us to have a 
 solid set of well-defined documentation tasks. Putting that 
 together is going to require help from the community. All of us 
 have encountered areas where improvement is needed in the spec, 
 the Phobos docs, and docs for dub, vibe.d, and many other tools 
 and projects around the D ecosystem. Some of it has made it 
 into Bugzilla (which will be mined for material), but much of 
 it has been buried in the forum archives or evaporated into the 
 ether from the IRC/Discord/Slack channels.

 This thread is a place to collect your documentation pain in 
 one place. I'm about to publish a blog post announcing this (a 
 few minutes after I hit 'Send' on this post):

 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/

 As I mention there, we need you to be as specific as you can. 
 What, specifically, is missing? What is unclear? What is 
 incorrect? Give as much detail as you can. We want to be able 
 to gather this info and define specific documentation tasks 
 that anyone can step in and complete with the information 
 provided.

 Any project in the D ecosystem is fair game. So please help us 
 out and tell us how D documentation can be improved for you.

 If you feel the urge to wax philosophical on something you see 
 here, please start a new thread and do all the philosophical 
 waxing you want there. Let's keep this one focused on listing 
 specific documentation issues. Do feel free to expand on any 
 post here with information you think is relevant.

 Thanks!
I would really like to see "Mir" library docs get more love: http://mir-algorithm.libmir.org Being a D beginner and coming from Python world I struggle to understand why and how some examples work. I lack trivial information and for the most part the context. How is mir.ndslice `Slice` entity is different from D multidimensional array and why is it different in the first place. What is the big purpose and goal of the library documentation? When should we prefer it over traditional D arrays, etc. etc. This stuff belongs in the library. Right now mir docs are dry and incomplete which is a shame since it could grow into a serious Numpy alternative and bring more people into D.
Mar 02
parent reply jmh530 <john.michael.hall gmail.com> writes:
On Monday, 2 March 2020 at 14:13:16 UTC, p.shkadzko wrote:
 [snip]

 I would really like to see "Mir" library docs get more love: 
 http://mir-algorithm.libmir.org

 Being a D beginner and coming from Python world I struggle to 
 understand why and how some examples work. I lack trivial 
 information and for the most part the context. How is 
 mir.ndslice `Slice` entity is different from D multidimensional 
 array and why is it different in the first place. What is the 
 big purpose and goal of the library documentation? When should 
 we prefer it over traditional D arrays, etc. etc. This stuff 
 belongs in the library. Right now mir docs are dry and 
 incomplete which is a shame since it could grow into a serious 
 Numpy alternative and bring more people into D.
I agree that there could be some improvement here. I've intended to write something up, but haven't. There is a blog post from Shigeki Karita that is listed in the readme.md that I recall doing a decent job, but it is in Japanese and Google Translate doesn't seem to run on it anymore. I think there is an issue with the certificate or something. Probably just making a English version of it more easily available would be a step in the right direction.
Mar 02
parent reply p.shkadzko <p.shkadzko gmail.com> writes:
On Monday, 2 March 2020 at 16:55:36 UTC, jmh530 wrote:
 On Monday, 2 March 2020 at 14:13:16 UTC, p.shkadzko wrote:
 [...]
I agree that there could be some improvement here. I've intended to write something up, but haven't. There is a blog post from Shigeki Karita that is listed in the readme.md that I recall doing a decent job, but it is in Japanese and Google Translate doesn't seem to run on it anymore. I think there is an issue with the certificate or something. Probably just making a English version of it more easily available would be a step in the right direction.
I'd love to help and write some docs. Maybe something like a simplistic tutorial that Numpy has would already be great.
Mar 03
parent jmh530 <john.michael.hall gmail.com> writes:
On Tuesday, 3 March 2020 at 15:30:40 UTC, p.shkadzko wrote:
 [snip]

 I'd love to help and write some docs. Maybe something like a 
 simplistic tutorial that Numpy has would already be great.
If you need someone to review it, I'd be happy to.
Mar 03
prev sibling next sibling parent bachmeier <no spam.net> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:

 This thread is a place to collect your documentation pain in 
 one place. I'm about to publish a blog post announcing this (a 
 few minutes after I hit 'Send' on this post):
We need documentation of strategies to optimize your code to get the best performance. There are numerous hacks that people suggest - look at this example https://forum.dlang.org/post/ezomjijivexzrwtbtahn forum.dlang.org but we should be able to link to a guide. Related to this, we need documentation on strategies to write programs without the GC.
Mar 02
prev sibling next sibling parent reply Panke <tobias pankrath.net> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 Preliminary discussions are underway for a new event to 
 encourage improvements to documentation across the D ecosystem. 
 I can't provide any details yet because the details aren't yet 
 fixed. I don't even know for sure it's going to happen.
Any news here?
May 02
parent reply Mike Parker <aldacron gmail.com> writes:
On Saturday, 2 May 2020 at 18:02:11 UTC, Panke wrote:
 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 Preliminary discussions are underway for a new event to 
 encourage improvements to documentation across the D 
 ecosystem. I can't provide any details yet because the details 
 aren't yet fixed. I don't even know for sure it's going to 
 happen.
Any news here?
Not yet. It's going to happen at some point if we can sort out enough concrete documentation tasks.
May 02
parent reply Jan =?UTF-8?B?SMO2bmln?= <hrominium gmail.com> writes:
On Sunday, 3 May 2020 at 01:37:54 UTC, Mike Parker wrote:
 Not yet. It's going to happen at some point if we can sort out 
 enough concrete documentation tasks.
Insight from a D newcomer for easier Dlang accessibility. Not everything is documentation per se: - promote wiki.dlang.org directly on D's webpage - promote authors to copy/write/(at least link) articles/tutorials/cookbooks on the wiki (there are many, but also many are scattered threw out the web) - copy Dlang's blog to wiki (keep the blog, but collect information in one place. Plus points if directly sorted what the blog post was: article/tutorial/cookbook) - declare unmaintained packages as such (once a month I read the question, whether derelict works, and once a month Mike answers, that he does not maintain it anymore. And this goes on for many packages. In addition it is hard to a newcomer to see, whether a package is abandoned, or finished. Example: coming from python word, anything which didn't have a commit in last 2 years is fishy) ( I don't want to attack you Mike, it is just an example, but since you are the one I am answering right now, it is the example) - decrease score of packages, which don't build on code.dlang.org - Language and library reference have enough examples (at least the parts I use). Examples are simple and clear. However to a newcomer needs also more complex examples, like tutorials or cookbooks. Idea: one link, on the specific reference to a section with related articles/tutorials/cookbooks. - opinionated suggestions in getting started https://wiki.dlang.org/Getting_Started (a newcomer is overwhelmed by the possibilities of compilers,editors/ides. Suggestions: dmd, vscodium with code-d) - probably pack this task list somewhere on the wiki - Encourage newcomers to edit the wiki. This is a simple task, often dull to do for experienced community members, but great for newcomers, because they are included AND they explore the wiki ant the community on themselves.
May 03
parent reply Jan =?UTF-8?B?SMO2bmln?= <hrominium gmail.com> writes:
On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:
 - Encourage newcomers to edit the wiki. This is a simple task, 
 often dull to do for experienced community members, but great 
 for newcomers, because they are included AND they explore the 
 wiki ant the community on themselves.
I felt encouraged today, so I created this list[1] I hope it was OK. Please feel free to fill, sort & enhance. [1]: https://wiki.dlang.org/Documentation_improvement_initiative
May 05
parent reply Mike Parker <aldacron gmail.com> writes:
On Tuesday, 5 May 2020 at 16:05:44 UTC, Jan Hönig wrote:
 On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:
 - Encourage newcomers to edit the wiki. This is a simple task, 
 often dull to do for experienced community members, but great 
 for newcomers, because they are included AND they explore the 
 wiki ant the community on themselves.
I felt encouraged today, so I created this list[1] I hope it was OK. Please feel free to fill, sort & enhance. [1]: https://wiki.dlang.org/Documentation_improvement_initiative
Thanks! I'm still looking for documentation tasks that require enough work that we can use them for the event. Adding one or two lines here or there isn't enough. And something that requires weeks is too much. We're looking for things that can be accomplished in terms of hours or days.
May 05
parent reply WebFreak001 <d.forum webfreak.org> writes:
On Wednesday, 6 May 2020 at 02:34:33 UTC, Mike Parker wrote:
 On Tuesday, 5 May 2020 at 16:05:44 UTC, Jan Hönig wrote:
 On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:
 - Encourage newcomers to edit the wiki. This is a simple 
 task, often dull to do for experienced community members, but 
 great for newcomers, because they are included AND they 
 explore the wiki ant the community on themselves.
I felt encouraged today, so I created this list[1] I hope it was OK. Please feel free to fill, sort & enhance. [1]: https://wiki.dlang.org/Documentation_improvement_initiative
Thanks! I'm still looking for documentation tasks that require enough work that we can use them for the event. Adding one or two lines here or there isn't enough. And something that requires weeks is too much. We're looking for things that can be accomplished in terms of hours or days.
How about also cleaning up documentation how it looks on the web? Like missing macros are rendered blank in ddox, so the usage or the definition could get fixed. Example missing something: https://vibed.org/api/vibe.db.mongo.mongo/ (ending with "a dedicated utility for this called .", missing the $(LINK2 ...) macro) ddox also doesn't support showing mixin templates yet, which are however already reported in the JSON by the dmd documentation generator thing and only need some implementation. Also something I'm finding essential and think should be added to the DDoc spec: $(LREF) and $(REF) - they are used a lot in phobos and (a bit biased) they are also implemented in the code-d doc preview / code tips already for all packages, making them look nicely already there. Even if it just suggests that these are subject to implementation for each documentation generator, having a well defined syntax and explanation would help a lot.
May 05
next sibling parent Jan =?UTF-8?B?SMO2bmln?= <hrominium gmail.com> writes:
On Wednesday, 6 May 2020 at 05:25:59 UTC, WebFreak001 wrote:
 How about also cleaning up documentation how it looks on the 
 web? Like missing macros are rendered blank in ddox, so the 
 usage or the definition could get fixed. Example missing 
 something: https://vibed.org/api/vibe.db.mongo.mongo/ (ending 
 with "a dedicated utility for this called .", missing the 
 $(LINK2 ...) macro)

 ddox also doesn't support showing mixin templates yet, which 
 are however already reported in the JSON by the dmd 
 documentation generator thing and only need some implementation.

 Also something I'm finding essential and think should be added 
 to the DDoc spec: $(LREF) and $(REF) - they are used a lot in 
 phobos and (a bit biased) they are also implemented in the 
 code-d doc preview / code tips already for all packages, making 
 them look nicely already there. Even if it just suggests that 
 these are subject to implementation for each documentation 
 generator, having a well defined syntax and explanation would 
 help a lot.
Please add it to the wiki. https://wiki.dlang.org/Documentation_improvement_initiative#The_List
May 06
prev sibling parent reply David Gileadi <gileadisNOSPM gmail.com> writes:
On 5/5/20 10:25 PM, WebFreak001 wrote:
 On Wednesday, 6 May 2020 at 02:34:33 UTC, Mike Parker wrote:
 On Tuesday, 5 May 2020 at 16:05:44 UTC, Jan Hönig wrote:
 On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:
 - Encourage newcomers to edit the wiki. This is a simple task, often 
 dull to do for experienced community members, but great for 
 newcomers, because they are included AND they explore the wiki ant 
 the community on themselves.
I felt encouraged today, so I created this list[1] I hope it was OK. Please feel free to fill, sort & enhance. [1]: https://wiki.dlang.org/Documentation_improvement_initiative
Thanks! I'm still looking for documentation tasks that require enough work that we can use them for the event. Adding one or two lines here or there isn't enough. And something that requires weeks is too much. We're looking for things that can be accomplished in terms of hours or days.
How about also cleaning up documentation how it looks on the web? Like missing macros are rendered blank in ddox, so the usage or the definition could get fixed. Example missing something: https://vibed.org/api/vibe.db.mongo.mongo/ (ending with "a dedicated utility for this called .", missing the $(LINK2 ...) macro) ddox also doesn't support showing mixin templates yet, which are however already reported in the JSON by the dmd documentation generator thing and only need some implementation. Also something I'm finding essential and think should be added to the DDoc spec: $(LREF) and $(REF) - they are used a lot in phobos and (a bit biased) they are also implemented in the code-d doc preview / code tips already for all packages, making them look nicely already there. Even if it just suggests that these are subject to implementation for each documentation generator, having a well defined syntax and explanation would help a lot.
Incidentally in my -preview=markdown changes putting a symbol in brackets (using Markdown syntax for a link) like [string] creates a link to that symbol's definition [1]. I suspect my implementation isn't perfect, but like the rest of the -preview=markdown changes my hope is that it makes the docs easier to write. [1]: https://dlang.org/spec/ddoc.html#reference_links
May 06
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 6 May 2020 at 14:24:53 UTC, David Gileadi wrote:
 Incidentally in my -preview=markdown changes putting a symbol 
 in brackets (using Markdown syntax for a link) like [string] 
 creates a link to that symbol's definition
Yeah, my adrdox does something similar. http://dpldocs.info/experimental-docs/adrdox.syntax.html#cross-referencing I also rewrite REF and LREF into it for phobos compatibility internally but it is a pretty obvious win to define these. (actually adrdox defines EVERYTHING and doesn't allow user-defined macros at all. Standardization makes it easier to use here. I just hard-coded the supported ones and leave the rest the unmodified.)
May 06
prev sibling parent reply Guillaume Piolat <first.last gmail.com> writes:
On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 Preliminary discussions are underway for a new event to 
 encourage improvements to documentation across the D ecosystem. 
 I can't provide any details yet because the details aren't yet 
 fixed. I don't even know for sure it's going to happen.

 However, the best way to make it happen is for us to have a 
 solid set of well-defined documentation tasks. Putting that 
 together is going to require help from the community. All of us 
 have encountered areas where improvement is needed in the spec, 
 the Phobos docs, and docs for dub, vibe.d, and many other tools 
 and projects around the D ecosystem. Some of it has made it 
 into Bugzilla (which will be mined for material), but much of 
 it has been buried in the forum archives or evaporated into the 
 ether from the IRC/Discord/Slack channels.

 This thread is a place to collect your documentation pain in 
 one place. I'm about to publish a blog post announcing this (a 
 few minutes after I hit 'Send' on this post):

 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/

 As I mention there, we need you to be as specific as you can. 
 What, specifically, is missing? What is unclear? What is 
 incorrect? Give as much detail as you can. We want to be able 
 to gather this info and define specific documentation tasks 
 that anyone can step in and complete with the information 
 provided.

 Any project in the D ecosystem is fair game. So please help us 
 out and tell us how D documentation can be improved for you.
Recently I spent more than 15 minutes trying to **get the Date of today** with std.datetime. The answer is: import std.datetime; Date today() { SysTime time = Clock.currTime(); return Date(time.year, time.month, time.day); } to do it you need to know what a SysTime is, what Clock is. It's the kind of examples that would really improve life for the stdlib user, with simple copy-pasting often being enough. Another one I'm using constantly is: /// Returns: Most precise clock ticks, in microseconds. long getTickUs() nothrow nogc { import core.time; return convClockFreq(MonoTime.currTime.ticks, MonoTime.ticksPerSecond, 1_000_000); } **It's not trivial at all either!** I think small example for common tasks like can bring back some productivity. On the contrary, `read` the most useful function of `std.file`, has an example: https://dlang.org/phobos/std_file.html#.read
May 08
next sibling parent Steven Schveighoffer <schveiguy gmail.com> writes:
On 5/8/20 11:34 AM, Guillaume Piolat wrote:
 On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
 Preliminary discussions are underway for a new event to encourage 
 improvements to documentation across the D ecosystem. I can't provide 
 any details yet because the details aren't yet fixed. I don't even 
 know for sure it's going to happen.

 However, the best way to make it happen is for us to have a solid set 
 of well-defined documentation tasks. Putting that together is going to 
 require help from the community. All of us have encountered areas 
 where improvement is needed in the spec, the Phobos docs, and docs for 
 dub, vibe.d, and many other tools and projects around the D ecosystem. 
 Some of it has made it into Bugzilla (which will be mined for 
 material), but much of it has been buried in the forum archives or 
 evaporated into the ether from the IRC/Discord/Slack channels.

 This thread is a place to collect your documentation pain in one 
 place. I'm about to publish a blog post announcing this (a few minutes 
 after I hit 'Send' on this post):

 http://dlang.org/blog/2020/02/17/news-update-swag…on-help-and-more/

 As I mention there, we need you to be as specific as you can. What, 
 specifically, is missing? What is unclear? What is incorrect? Give as 
 much detail as you can. We want to be able to gather this info and 
 define specific documentation tasks that anyone can step in and 
 complete with the information provided.

 Any project in the D ecosystem is fair game. So please help us out and 
 tell us how D documentation can be improved for you.
Recently I spent more than 15 minutes trying to **get the Date of today** with std.datetime. The answer is:     import std.datetime;     Date today()     {         SysTime time = Clock.currTime();         return Date(time.year, time.month, time.day);     } to do it you need to know what a SysTime is, what Clock is.
You can do: return cast(Date)Clock.currTime; Though I have never liked the requirement to cast. There really should just be a Date.currDate or SysTime.date accessor.
 
 Another one I'm using constantly is:
 
 
     /// Returns: Most precise clock ticks, in microseconds.
     long getTickUs() nothrow  nogc
     {
        import core.time;
        return convClockFreq(MonoTime.currTime.ticks, 
 MonoTime.ticksPerSecond, 1_000_000);
     }
 
 **It's not trivial at all either!**
 I think small example for common tasks like can bring back some 
 productivity.
This one is easier: (MonoTime.currTime - MonoTime.zero).total!"usecs"; -Steve
May 08
prev sibling parent reply jmh530 <john.michael.hall gmail.com> writes:
On Friday, 8 May 2020 at 15:34:43 UTC, Guillaume Piolat wrote:
 [snip]

 Recently I spent more than 15 minutes trying to **get the Date 
 of today** with std.datetime.


 The answer is:


     import std.datetime;
     Date today()
     {
         SysTime time = Clock.currTime();
         return Date(time.year, time.month, time.day);
     }
 [snip]
I think this should be in phobos, regardless of the documentation improvement.
May 08
parent Jan =?UTF-8?B?SMO2bmln?= <hrominium gmail.com> writes:
Today I was very satisfied with the dub documentation.

However I don't know if anyone has actually done anything, or 
duckduckgo just actually finds it now.

(More specifically this: https://dub.pm/package-format-json.html)

So either I was too stupid to properly search half a year a ago, 
or someone did a tremendous job meanwhile (which I missed).

I updated 
https://wiki.dlang.org/Documentation_improvement_initiative
Jun 25