Documentation Improvement Initiative

[Guillaume Piolat]

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