Github user HyukjinKwon commented on a diff in the pull request: https://github.com/apache/spark/pull/18749#discussion_r130223158 --- Diff: sql/catalyst/src/main/java/org/apache/spark/sql/catalyst/expressions/ExpressionDescription.java --- @@ -24,20 +24,50 @@ /** * ::DeveloperApi:: - + * * A function description type which can be recognized by FunctionRegistry, and will be used to * show the usage of the function in human language. * * `usage()` will be used for the function usage in brief way. - * `extended()` will be used for the function usage in verbose way, suppose - * an example will be provided. * - * And we can refer the function name by `_FUNC_`, in `usage` and `extended`, as it's + * These below are concatenated and used for the function usage in verbose way, suppose arguments, + * examples, note and since will be provided. + * + * `arguments()` describes arguments for the expression. This should follow the format as below: + * + * Arguments: + * * arg0 - ... + * .... + * * arg1 - ... + * .... + * + * `examples()` describes examples for the expression. This should follow the format as below: + * + * Examples: + * > SELECT ...; + * ... + * > SELECT ...; + * ... + * + * `note()` contains some notes for the expression optionally. + * + * `since()` contains version information for the expression. Version is specified by, + * for example, "2.2.0". + * + * We can refer the function name by `_FUNC_`, in `usage`, `arguments` and `examples`, as it's * registered in `FunctionRegistry`. + * + * Note that, if `extended()` is defined, `arguments()`, `examples()`, `note()` and `since()` will + * be ignored and `extended()` will be used for the extended description for backward + * compatibility. */ @DeveloperApi @Retention(RetentionPolicy.RUNTIME) public @interface ExpressionDescription { - String usage() default "_FUNC_ is undocumented"; - String extended() default "\n No example/argument for _FUNC_.\n"; + String usage() default ""; + String extended() default ""; --- End diff -- In the last commit https://github.com/apache/spark/pull/18749/commits/bf48875057ca5978b88cacab455292b64daf1557, I tried to keep the original behaviour and compatibility (although I guess we are fine to break this as said in few comments above): For `ExpressionDescription` and `ExpressionInfo`, if `extended` is an empty string (the default value), it creates the `extended` made by `arguments`, `examples`, `note` and `since` and use this as the extended description. if `extended` is a non-empty string, it ignores the new `arguments`, `examples`, `note` and `since` but use this as the extended description, assuming this was set manually.
--- If your project is set up for it, you can reply to this email and have your reply appear on GitHub as well. If your project does not have this feature enabled and wishes so, or if the feature is enabled but not working, please contact infrastructure at infrastruct...@apache.org or file a JIRA ticket with INFRA. --- --------------------------------------------------------------------- To unsubscribe, e-mail: reviews-unsubscr...@spark.apache.org For additional commands, e-mail: reviews-h...@spark.apache.org