[phobos] std.process deprecations

[Jonathan M Davis via phobos]

> Sent: Thursday, August 07, 2014 at 1:21 AM
> From: "Lars Tandle Kyllingstad via phobos" <phobos at puremagic.com>
> To: phobos at puremagic.com
> Subject: Re: [phobos] std.process deprecations
>
> On 07/08/14 01:12, Jonathan M Davis via phobos wrote:
> > We really aren't "scheduling" anything for deprecation anymore, which is
> > probably why I missed those functions and have never actually deprecated them
> > when I last was moving the Phobos deprecations along. Now that deprecated just
> > prints out a message rather than blocking compilation, there's no reason not
> > to just immediately deprecate anything that we want to deprecate. So, if we're
> > going to deprecate them, we should just deprecate them.
>
> Ok, got it.  How long do functions stay deprecated before they're
> removed, then?

I generally try for one year as deprecated and six months as deprecated but
undocumented. Ideally, those dates would be from actual releases, but those
have gotten so far apart now that that isn't working so well. So, when
something is deprecated, I put a comment like

$(RED Deprecated. Please use $(LREF PointerTarget) instead. This will be
      removed in June 2015.)

or

$(RED Deprecated. Please use $(LREF split) instead. Too frequently,
      $(LREF get) or one of the individual unit getters is used when the
      function that gave the desired behavior was $(LREF total). This
      should make it more explicit and help prevent bugs. This function
      will be removed in June 2015.)

at the top of the ddoc comment for the function, and then around the date
given in the comment (June 2015 in this case), the entire ddoc comment gets
replaced with something like

// Explicitly undocumented. It will be removed in December 2015.

and then in the date given in that comment, the function would be completely
removed.

- Jonathan M Davis