[GitHub] spark pull request #18749: [SPARK-21485][FOLLOWUP][SQL][DOCS] Describes exam...

[srowen <gi...@git.apache.org>]

Github user srowen commented on a diff in the pull request:

    https://github.com/apache/spark/pull/18749#discussion_r129929153
  
    --- Diff: sql/catalyst/src/main/java/org/apache/spark/sql/catalyst/expressions/ExpressionDescription.java ---
    @@ -29,15 +29,40 @@
      * 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`.
      */
     @DeveloperApi
    --- End diff --
    
    Agree, that's my only question, whether this change matters, because it's a developer API. You provide default implementations, though `extended()` gets removed. Hm. I am wondering if it's possible to keep `extended()` but, well, ignore it? it would at least be compatible even if it meant someone's implementation out there would have to update to provide information to `ExpressionInfo` correctly. That's not really a functional problem though.


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org