Fix issue 16993: Clarify documentation of std.datetime's toString fun…

…ctions.

I should have done this years ago, but this makes the documentation
clear that std.datetime's toString is intended simply for easy printing
of the type rather than for code that actually cares about the format of
the string. There are other, explicit functions for code that actually
cares.

std/datetime/date.d

@@ -3048,6 +3048,26 @@ public:
 
     /++
         Converts this $(LREF DateTime) to a string.
+
+        This function exists to make it easy to convert a $(LREF DateTime) to a
+        string for code that does not care what the exact format is - just that
+        it presents the information in a clear manner. It also makes it easy to
+        simply convert a $(LREF DateTime) to a string when using functions such
+        as `to!string`, `format`, or `writeln` which use toString to convert
+        user-defined types. So, it is unlikely that much code will call
+        toString directly.
+
+        The format of the string is purposefully unspecified, and code that
+        cares about the format of the string should use `toISOString`,
+        `toISOExtString`, `toSimpleString`, or some other custom formatting
+        function that explicitly generates the format that the code needs. The
+        reason is that the code is then clear about what format it's using,
+        making it less error-prone to maintain the code and interact with other
+        software that consumes the generated strings. It's for this same reason
+        that $(LREF DateTime) has no `fromString` function, whereas it does have
+        `fromISOString`, `fromISOExtString`, and `fromSimpleString`.
+
+        The format returned by toString may or may not change in the future.
       +/
     string toString() const @safe pure nothrow
     {
@@ -7281,18 +7301,32 @@ public:
 
     /++
         Converts this $(LREF Date) to a string.
+
+        This function exists to make it easy to convert a $(LREF Date) to a
+        string for code that does not care what the exact format is - just that
+        it presents the information in a clear manner. It also makes it easy to
+        simply convert a $(LREF Date) to a string when using functions such as
+        `to!string`, `format`, or `writeln` which use toString to convert
+        user-defined types. So, it is unlikely that much code will call
+        toString directly.
+
+        The format of the string is purposefully unspecified, and code that
+        cares about the format of the string should use `toISOString`,
+        `toISOExtString`, `toSimpleString`, or some other custom formatting
+        function that explicitly generates the format that the code needs. The
+        reason is that the code is then clear about what format it's using,
+        making it less error-prone to maintain the code and interact with other
+        software that consumes the generated strings. It's for this same reason
+        $(LREF Date) has no `fromString` function, whereas it does have
+        `fromISOString`, `fromISOExtString`, and `fromSimpleString`.
+
+        The format returned by toString may or may not change in the future.
       +/
     string toString() const @safe pure nothrow
     {
         return toSimpleString();
     }
 
-    ///
-    @safe unittest
-    {
-        assert(Date(2010, 7, 4).toString() == "2010-Jul-04");
-    }
-
     @safe unittest
     {
         auto date = Date(1999, 7, 6);
@@ -8804,6 +8838,26 @@ public:
 
     /++
         Converts this TimeOfDay to a string.
+
+        This function exists to make it easy to convert a $(LREF TimeOfDay) to a
+        string for code that does not care what the exact format is - just that
+        it presents the information in a clear manner. It also makes it easy to
+        simply convert a $(LREF TimeOfDay) to a string when using functions such
+        as `to!string`, `format`, or `writeln` which use toString to convert
+        user-defined types. So, it is unlikely that much code will call
+        toString directly.
+
+        The format of the string is purposefully unspecified, and code that
+        cares about the format of the string should use `toISOString`,
+        `toISOExtString`, or some other custom formatting function that
+        explicitly generates the format that the code needs. The reason is that
+        the code is then clear about what format it's using, making it less
+        error-prone to maintain the code and interact with other software that
+        consumes the generated strings. It's for this same reason that
+        $(LREF TimeOfDay) has no `fromString` function, whereas it does have
+        `fromISOString` and `fromISOExtString`.
+
+        The format returned by toString may or may not change in the future.
       +/
     string toString() const @safe pure nothrow
     {

std/datetime/systime.d

@@ -8180,6 +8180,26 @@ public:
 
     /++
         Converts this $(LREF SysTime) to a string.
+
+        This function exists to make it easy to convert a $(LREF SysTime) to a
+        string for code that does not care what the exact format is - just that
+        it presents the information in a clear manner. It also makes it easy to
+        simply convert a $(LREF SysTime) to a string when using functions such
+        as `to!string`, `format`, or `writeln` which use toString to convert
+        user-defined types. So, it is unlikely that much code will call
+        toString directly.
+
+        The format of the string is purposefully unspecified, and code that
+        cares about the format of the string should use `toISOString`,
+        `toISOExtString`, `toSimpleString`, or some other custom formatting
+        function that explicitly generates the format that the code needs. The
+        reason is that the code is then clear about what format it's using,
+        making it less error-prone to maintain the code and interact with other
+        software that consumes the generated strings. It's for this same reason
+        that $(LREF SysTime) has no `fromString` function, whereas it does have
+        `fromISOString`, `fromISOExtString`, and `fromSimpleString`.
+
+        The format returned by toString may or may not change in the future.
       +/
     string toString() @safe const nothrow
     {