Improve temporal columns docblocks

laravel · Nov 13, 2017 · 6ee8d8f · 6ee8d8f
1 parent 09942f1
commit 6ee8d8f
Show file tree

Hide file tree

Showing 5 changed files with 60 additions and 24 deletions.
diff --git a/src/Illuminate/Database/Schema/Blueprint.php b/src/Illuminate/Database/Schema/Blueprint.php
@@ -784,7 +784,7 @@ public function dateTime($column, $precision = 0)
     }
 
     /**
-     * Create a new date-time column (with time zone) on the table.
+     * Create a new date-time (with time zone) column on the table.
      *
      * @param  string  $column
      * @param  int  $precision
@@ -808,7 +808,7 @@ public function time($column, $precision = 0)
     }
 
     /**
-     * Create a new time column (with time zone) on the table.
+     * Create a new time (with time zone) column on the table.
      *
      * @param  string  $column
      * @param  int  $precision
@@ -844,7 +844,7 @@ public function timestampTz($column, $precision = 0)
     }
 
     /**
-     * Add nullable creation and update timestamps to the table.
+     * Add nullable creation and update timestamps columns to the table.
      *
      * @param  int  $precision
      * @return void
@@ -857,7 +857,7 @@ public function timestamps($precision = 0)
     }
 
     /**
-     * Add nullable creation and update timestamps to the table.
+     * Add nullable creation and update timestamps columns to the table.
      *
      * Alias for self::timestamps().
      *
@@ -870,7 +870,7 @@ public function nullableTimestamps($precision = 0)
     }
 
     /**
-     * Add creation and update timestampTz columns to the table.
+     * Add nullable creation and update timestamps (with time zone) columns to the table.
      *
      * @param  int  $precision
      * @return void
@@ -883,7 +883,7 @@ public function timestampsTz($precision = 0)
     }
 
     /**
-     * Add a "deleted at" timestamp for the table.
+     * Add a nullable deletion timestamp column to the table.
      *
      * @param  string  $column
      * @param  int  $precision
@@ -895,7 +895,7 @@ public function softDeletes($column = 'deleted_at', $precision = 0)
     }
 
     /**
-     * Add a "deleted at" timestampTz for the table.
+     * Add a nullable deletion timestamp (with time zone) column to the table.
      *
      * @param  int  $precision
      * @return \Illuminate\Support\Fluent

diff --git a/src/Illuminate/Database/Schema/Grammars/MySqlGrammar.php b/src/Illuminate/Database/Schema/Grammars/MySqlGrammar.php
@@ -577,6 +577,8 @@ protected function typeJsonb(Fluent $column)
     /**
      * Create the column definition for a date type.
      *
+     * @see https://dev.mysql.com/doc/refman/5.7/en/datetime.html
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -588,6 +590,8 @@ protected function typeDate(Fluent $column)
     /**
      * Create the column definition for a date-time type.
      *
+     * @see https://dev.mysql.com/doc/refman/5.7/en/datetime.html
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -599,7 +603,7 @@ protected function typeDateTime(Fluent $column)
     }
 
     /**
-     * Create the column definition for a date-time type.
+     * Create the column definition for a date-time (with time zone) type.
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
@@ -612,6 +616,8 @@ protected function typeDateTimeTz(Fluent $column)
     /**
      * Create the column definition for a time type.
      *
+     * @see https://dev.mysql.com/doc/refman/5.7/en/time.html
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -621,7 +627,7 @@ protected function typeTime(Fluent $column)
     }
 
     /**
-     * Create the column definition for a time type.
+     * Create the column definition for a time (with time zone) type.
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
@@ -634,6 +640,8 @@ protected function typeTimeTz(Fluent $column)
     /**
      * Create the column definition for a timestamp type.
      *
+     * @see https://dev.mysql.com/doc/refman/5.7/en/datetime.html
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -645,7 +653,7 @@ protected function typeTimestamp(Fluent $column)
     }
 
     /**
-     * Create the column definition for a timestamp type.
+     * Create the column definition for a timestamp (with time zone) type.
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string

diff --git a/src/Illuminate/Database/Schema/Grammars/PostgresGrammar.php b/src/Illuminate/Database/Schema/Grammars/PostgresGrammar.php
@@ -528,6 +528,8 @@ protected function typeJsonb(Fluent $column)
     /**
      * Create the column definition for a date type.
      *
+     * @see https://www.postgresql.org/docs/current/static/datatype-datetime.html
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -550,7 +552,7 @@ protected function typeDateTime(Fluent $column)
     }
 
     /**
-     * Create the column definition for a date-time type.
+     * Create the column definition for a date-time (with time zone) type.
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
@@ -563,6 +565,8 @@ protected function typeDateTimeTz(Fluent $column)
     /**
      * Create the column definition for a time type.
      *
+     * @see https://www.postgresql.org/docs/current/static/datatype-datetime.html
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -574,7 +578,9 @@ protected function typeTime(Fluent $column)
     }
 
     /**
-     * Create the column definition for a time type.
+     * Create the column definition for a time (with time zone) type.
+     *
+     * @see https://www.postgresql.org/docs/current/static/datatype-datetime.html
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
@@ -589,6 +595,8 @@ protected function typeTimeTz(Fluent $column)
     /**
      * Create the column definition for a timestamp type.
      *
+     * @see https://www.postgresql.org/docs/current/static/datatype-datetime.html
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -600,7 +608,9 @@ protected function typeTimestamp(Fluent $column)
     }
 
     /**
-     * Create the column definition for a timestamp type.
+     * Create the column definition for a timestamp (with time zone) type.
+     *
+     * @see https://www.postgresql.org/docs/current/static/datatype-datetime.html
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string

diff --git a/src/Illuminate/Database/Schema/Grammars/SQLiteGrammar.php b/src/Illuminate/Database/Schema/Grammars/SQLiteGrammar.php
@@ -537,6 +537,10 @@ protected function typeJsonb(Fluent $column)
     /**
      * Create the column definition for a date type.
      *
+     * Note: SQLite does not have a storage class set aside for storing dates and/or times.
+     *
+     * @see https://sqlite.org/datatype3.html#date_and_time_datatype
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -550,6 +554,10 @@ protected function typeDate(Fluent $column)
     /**
      * Create the column definition for a date-time type.
      *
+     * Note: SQLite does not have a storage class set aside for storing dates and/or times.
+     *
+     * @see https://sqlite.org/datatype3.html#date_and_time_datatype
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -561,10 +569,7 @@ protected function typeDateTime(Fluent $column)
     }
 
     /**
-     * Create the column definition for a date-time type.
-     *
-     * Note: "SQLite does not have a storage class set aside for storing dates and/or times."
-     * @link https://www.sqlite.org/datatype3.html
+     * Create the column definition for a date-time (with time zone) type.
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
@@ -577,6 +582,10 @@ protected function typeDateTimeTz(Fluent $column)
     /**
      * Create the column definition for a time type.
      *
+     * Note: SQLite does not have a storage class set aside for storing dates and/or times.
+     *
+     * @see https://sqlite.org/datatype3.html#date_and_time_datatype
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -588,7 +597,7 @@ protected function typeTime(Fluent $column)
     }
 
     /**
-     * Create the column definition for a time type.
+     * Create the column definition for a time (with time zone) type.
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
@@ -610,7 +619,7 @@ protected function typeTimestamp(Fluent $column)
     }
 
     /**
-     * Create the column definition for a timestamp type.
+     * Create the column definition for a timestamp (with time zone) type.
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string

diff --git a/src/Illuminate/Database/Schema/Grammars/SqlServerGrammar.php b/src/Illuminate/Database/Schema/Grammars/SqlServerGrammar.php
@@ -480,6 +480,8 @@ protected function typeJsonb(Fluent $column)
     /**
      * Create the column definition for a date type.
      *
+     * @see https://docs.microsoft.com/en-us/sql/t-sql/data-types/date-transact-sql
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -493,6 +495,11 @@ protected function typeDate(Fluent $column)
     /**
      * Create the column definition for a date-time type.
      *
+     * Note: DATETIME is being used in place of DATETIME2(0) for SQL Server 2005 compatibility
+     *
+     * @see https://docs.microsoft.com/en-us/sql/t-sql/data-types/datetime2-transact-sql
+     * @see https://docs.microsoft.com/en-us/sql/t-sql/data-types/datetime-transact-sql
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -504,7 +511,9 @@ protected function typeDateTime(Fluent $column)
     }
 
     /**
-     * Create the column definition for a date-time type.
+     * Create the column definition for a date-time (with time zone) type.
+     *
+     * @see https://docs.microsoft.com/en-us/sql/t-sql/data-types/datetimeoffset-transact-sql
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
@@ -519,6 +528,8 @@ protected function typeDateTimeTz(Fluent $column)
     /**
      * Create the column definition for a time type.
      *
+     * @see https://docs.microsoft.com/en-us/sql/t-sql/data-types/time-transact-sql
+     *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
      */
@@ -530,7 +541,7 @@ protected function typeTime(Fluent $column)
     }
 
     /**
-     * Create the column definition for a time type.
+     * Create the column definition for a time (with time zone) type.
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string
@@ -552,9 +563,7 @@ protected function typeTimestamp(Fluent $column)
     }
 
     /**
-     * Create the column definition for a timestamp type.
-     *
-     * @link https://msdn.microsoft.com/en-us/library/bb630289(v=sql.120).aspx
+     * Create the column definition for a timestamp (with time zone) type.
      *
      * @param  \Illuminate\Support\Fluent  $column
      * @return string