From 9b28c2b09e1e41876c4bff49881a9814cbcc178c Mon Sep 17 00:00:00 2001 From: Gengliang Wang Date: Fri, 27 Aug 2021 13:00:12 -0700 Subject: [PATCH] [SPARK-36597][DOCS][3.2] Fix issues in SQL function docs ### What changes were proposed in this pull request? * the functions make_dt_interval and make_ym_interval should make it clear that some of the fields are optional * remove the `|` symbol from the doc of `bit_get` https://dist.apache.org/repos/dist/dev/spark/v3.2.0-rc1-docs/_site/api/sql/index.html#bit_get * Address one missing comment in https://github.com/apache/spark/pull/33824#discussion_r695405699 ### Why are the changes needed? Improve the documentation. ### Does this PR introduce _any_ user-facing change? No ### How was this patch tested? Build doc and preview: ![image](https://user-images.githubusercontent.com/1097932/130996918-8c1fff88-ef5a-434b-8445-df7140bad3ba.png) ![image](https://user-images.githubusercontent.com/1097932/130996954-0ced28e7-fb90-4fcc-857e-6ccc31dc3c09.png) ![image](https://user-images.githubusercontent.com/1097932/130955106-5ae32dfc-6e89-4e28-bb8a-6c1b5213051c.png) ![image](https://user-images.githubusercontent.com/1097932/130922351-2f0f262d-5624-4d08-ba83-dfa3ed0b646b.png) Closes #33857 from gengliangwang/SPARK-36597-3.2. Authored-by: Gengliang Wang Signed-off-by: Dongjoon Hyun --- project/SparkBuild.scala | 1 + .../sql/catalyst/expressions/bitwiseExpressions.scala | 8 ++++---- .../sql/catalyst/expressions/intervalExpressions.scala | 10 +++++++--- 3 files changed, 12 insertions(+), 7 deletions(-) diff --git a/project/SparkBuild.scala b/project/SparkBuild.scala index 8edc1710e8..93256bc9e0 100644 --- a/project/SparkBuild.scala +++ b/project/SparkBuild.scala @@ -967,6 +967,7 @@ object Unidoc { .map(_.filterNot(_.getCanonicalPath.contains("org/apache/spark/sql/internal"))) .map(_.filterNot(_.getCanonicalPath.contains("org/apache/spark/sql/hive"))) .map(_.filterNot(_.getCanonicalPath.contains("org/apache/spark/sql/catalog/v2/utils"))) + .map(_.filterNot(_.getCanonicalPath.contains("org.apache.spark.errors"))) .map(_.filterNot(_.getCanonicalPath.contains("org.apache.spark.sql.errors"))) .map(_.filterNot(_.getCanonicalPath.contains("org/apache/hive"))) .map(_.filterNot(_.getCanonicalPath.contains("org/apache/spark/sql/v2/avro"))) diff --git a/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/bitwiseExpressions.scala b/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/bitwiseExpressions.scala index 3940c65593..57ab9e2773 100644 --- a/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/bitwiseExpressions.scala +++ b/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/bitwiseExpressions.scala @@ -233,10 +233,10 @@ object BitwiseGetUtil { @ExpressionDescription( usage = """ - |_FUNC_(expr, pos) - Returns the value of the bit (0 or 1) at the specified position. - | The positions are numbered from right to left, starting at zero. - | The position argument cannot be negative. - """, + _FUNC_(expr, pos) - Returns the value of the bit (0 or 1) at the specified position. + The positions are numbered from right to left, starting at zero. + The position argument cannot be negative. + """, examples = """ Examples: > SELECT _FUNC_(11, 0); diff --git a/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/intervalExpressions.scala b/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/intervalExpressions.scala index 5b111d17cd..c799c69b9a 100644 --- a/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/intervalExpressions.scala +++ b/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/intervalExpressions.scala @@ -227,7 +227,7 @@ case class DivideInterval( // scalastyle:off line.size.limit @ExpressionDescription( - usage = "_FUNC_(years, months, weeks, days, hours, mins, secs) - Make interval from years, months, weeks, days, hours, mins and secs.", + usage = "_FUNC_([years[, months[, weeks[, days[, hours[, mins[, secs]]]]]]]) - Make interval from years, months, weeks, days, hours, mins and secs.", arguments = """ Arguments: * years - the number of years, positive or negative @@ -360,7 +360,7 @@ case class MakeInterval( // scalastyle:off line.size.limit @ExpressionDescription( - usage = "_FUNC_(days, hours, mins, secs) - Make DayTimeIntervalType duration from days, hours, mins and secs.", + usage = "_FUNC_([days[, hours[, mins[, secs]]]]) - Make DayTimeIntervalType duration from days, hours, mins and secs.", arguments = """ Arguments: * days - the number of days, positive or negative @@ -372,6 +372,8 @@ case class MakeInterval( Examples: > SELECT _FUNC_(1, 12, 30, 01.001001); 1 12:30:01.001001000 + > SELECT _FUNC_(2); + 2 00:00:00.000000000 > SELECT _FUNC_(100, null, 3); NULL """, @@ -436,7 +438,7 @@ case class MakeDTInterval( } @ExpressionDescription( - usage = "_FUNC_(years, months) - Make year-month interval from years, months.", + usage = "_FUNC_([years[, months]]) - Make year-month interval from years, months.", arguments = """ Arguments: * years - the number of years, positive or negative @@ -450,6 +452,8 @@ case class MakeDTInterval( 1-0 > SELECT _FUNC_(-1, 1); -0-11 + > SELECT _FUNC_(2); + 2-0 """, since = "3.2.0", group = "datetime_funcs")