review: clarify javadoc

Author: dimas-b

polaris-core/src/main/java/org/apache/polaris/core/persistence/BasePersistence.java

@@ -147,8 +147,14 @@ void deleteAllEntityGrantRecords(
 
   /**
    * Lookup an entity given its catalog id (which can be {@link
-   * org.apache.polaris.core.entity.PolarisEntityConstants#NULL_ID} for top-level entities) and its
-   * entityId.
+   * org.apache.polaris.core.entity.PolarisEntityConstants#NULL_ID} for top-level entities), its
+   * entityId and type code (from {@link PolarisEntityType#getCode()}.
+   *
+   * <p>The type code parameter is redundant but can be used to optimize implementations in some
+   * cases. All callers are required to provide a valid value for the type code parameter. If the
+   * given type code does not match the type code of the previously created entity with the
+   * specified {@code entityId}, implementations may still return the entity or may behave as if the
+   * entity were not found.
    *
    * @param callCtx call context
    * @param catalogId catalog id or NULL_ID