API: Improve Javadoc of listNamespaces() (#7196)

apache · May 31, 2023 · 1ea1852 · 1ea1852
1 parent 54119bd
commit 1ea1852
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 12 deletions.
diff --git a/api/src/main/java/org/apache/iceberg/catalog/SessionCatalog.java b/api/src/main/java/org/apache/iceberg/catalog/SessionCatalog.java
@@ -270,21 +270,40 @@ default void createNamespace(SessionContext context, Namespace namespace) {
    * method must return ["a"] in the result array.
    *
    * @param context session context
-   * @return an List of namespace {@link Namespace} names
+   * @return a List of namespace {@link Namespace} names
    */
   default List<Namespace> listNamespaces(SessionContext context) {
     return listNamespaces(context, Namespace.empty());
   }
 
   /**
-   * List namespaces from the namespace.
+   * List child namespaces from the namespace.
+   *
+   * <p>For two existing tables named 'a.b.c.table' and 'a.b.d.table', this method returns:
+   *
+   * <ul>
+   *   <li>Given: {@code Namespace.empty()}
+   *   <li>Returns: {@code Namespace.of("a")}
+   * </ul>
    *
-   * <p>For example, if table a.b.t exists, use 'SELECT NAMESPACE IN a' this method must return
-   * Namepace.of("a","b") {@link Namespace}.
+   * <ul>
+   *   <li>Given: {@code Namespace.of("a")}
+   *   <li>Returns: {@code Namespace.of("a", "b")}
+   * </ul>
+   *
+   * <ul>
+   *   <li>Given: {@code Namespace.of("a", "b")}
+   *   <li>Returns: {@code Namespace.of("a", "b", "c")} and {@code Namespace.of("a", "b", "d")}
+   * </ul>
+   *
+   * <ul>
+   *   <li>Given: {@code Namespace.of("a", "b", "c")}
+   *   <li>Returns: empty list, because there are no child namespaces
+   * </ul>
    *
    * @param context session context
    * @param namespace a {@link Namespace namespace}
-   * @return a List of namespace {@link Namespace} names
+   * @return a List of child {@link Namespace} names from the given namespace
    * @throws NoSuchNamespaceException If the namespace does not exist (optional)
    */
   List<Namespace> listNamespaces(SessionContext context, Namespace namespace);

diff --git a/api/src/main/java/org/apache/iceberg/catalog/SupportsNamespaces.java b/api/src/main/java/org/apache/iceberg/catalog/SupportsNamespaces.java
@@ -68,19 +68,38 @@ default void createNamespace(Namespace namespace) {
    * exist and must be returned by this discovery method. For example, if table a.b.t exists, this
    * method must return ["a"] in the result array.
    *
-   * @return an List of namespace {@link Namespace} names
+   * @return a List of namespace {@link Namespace} names
    */
   default List<Namespace> listNamespaces() {
     return listNamespaces(Namespace.empty());
   }
 
   /**
-   * List namespaces from the namespace.
+   * List child namespaces from the namespace.
    *
-   * <p>For example, if table a.b.t exists, use 'SELECT NAMESPACE IN a' this method must return
-   * Namepace.of("a","b") {@link Namespace}.
+   * <p>For two existing tables named 'a.b.c.table' and 'a.b.d.table', this method returns:
    *
-   * @return a List of namespace {@link Namespace} names
+   * <ul>
+   *   <li>Given: {@code Namespace.empty()}
+   *   <li>Returns: {@code Namespace.of("a")}
+   * </ul>
+   *
+   * <ul>
+   *   <li>Given: {@code Namespace.of("a")}
+   *   <li>Returns: {@code Namespace.of("a", "b")}
+   * </ul>
+   *
+   * <ul>
+   *   <li>Given: {@code Namespace.of("a", "b")}
+   *   <li>Returns: {@code Namespace.of("a", "b", "c")} and {@code Namespace.of("a", "b", "d")}
+   * </ul>
+   *
+   * <ul>
+   *   <li>Given: {@code Namespace.of("a", "b", "c")}
+   *   <li>Returns: empty list, because there are no child namespaces
+   * </ul>
+   *
+   * @return a List of child {@link Namespace} names from the given namespace
    * @throws NoSuchNamespaceException If the namespace does not exist (optional)
    */
   List<Namespace> listNamespaces(Namespace namespace) throws NoSuchNamespaceException;

diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml
@@ -194,8 +194,10 @@ paths:
       summary: List namespaces, optionally providing a parent namespace to list underneath
       description:
         List all namespaces at a certain level, optionally starting from a given parent namespace.
-        For example, if table accounting.tax.paid exists, using 'SELECT NAMESPACE IN accounting' would
-        translate into `GET /namespaces?parent=accounting` and must return a namespace, ["accounting", "tax"].
+        If table accounting.tax.paid.info exists, using 'SELECT NAMESPACE IN accounting' would
+        translate into `GET /namespaces?parent=accounting` and must return a namespace, ["accounting", "tax"] only.
+        Using 'SELECT NAMESPACE IN accounting.tax' would
+        translate into `GET /namespaces?parent=accounting%1Ftax` and must return a namespace, ["accounting", "tax", "paid"].
         If `parent` is not provided, all top-level namespaces should be listed.
       operationId: listNamespaces
       parameters: