Documentation Improvement Initiative

[Steven Schveighoffer]

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