From 4aff011781bac7f1ab06052c74b1e418e9d1f792 Mon Sep 17 00:00:00 2001 From: Colin Alworth Date: Tue, 7 Nov 2023 11:41:01 -0600 Subject: [PATCH] Clean up javadoc, adding link references where appropriate --- .../io/deephaven/web/client/api/JsTable.java | 5 +- .../web/client/api/filter/FilterValue.java | 13 +++-- .../web/client/api/tree/JsTreeTable.java | 51 ++++++++++--------- 3 files changed, 38 insertions(+), 31 deletions(-) diff --git a/web/client-api/src/main/java/io/deephaven/web/client/api/JsTable.java b/web/client-api/src/main/java/io/deephaven/web/client/api/JsTable.java index a10f5cf7808..7d4c90f38cc 100644 --- a/web/client-api/src/main/java/io/deephaven/web/client/api/JsTable.java +++ b/web/client-api/src/main/java/io/deephaven/web/client/api/JsTable.java @@ -386,9 +386,8 @@ public String[] getAttributes() { } /** - * null if no property exists, a string if it is an easily serializable property, or a Promise - * - * that will either resolve with a table or error out if the object can't be passed to JS. + * null if no property exists, a string if it is an easily serializable property, or a {@code Promise + * <Table>} that will either resolve with a table or error out if the object can't be passed to JS. * * @param attributeName * @return Object diff --git a/web/client-api/src/main/java/io/deephaven/web/client/api/filter/FilterValue.java b/web/client-api/src/main/java/io/deephaven/web/client/api/filter/FilterValue.java index 7af38fb4646..a224489cd6b 100644 --- a/web/client-api/src/main/java/io/deephaven/web/client/api/filter/FilterValue.java +++ b/web/client-api/src/main/java/io/deephaven/web/client/api/filter/FilterValue.java @@ -20,6 +20,8 @@ import io.deephaven.web.client.api.Column; import io.deephaven.web.client.api.DateWrapper; import io.deephaven.web.client.api.LongWrapper; +import io.deephaven.web.client.api.TableData; +import io.deephaven.web.client.api.i18n.JsTimeZone; import javaemul.internal.annotations.DoNotAutobox; import jsinterop.annotations.JsIgnore; import jsinterop.annotations.JsMethod; @@ -101,12 +103,13 @@ public static FilterValue ofNumber(double input) { /** * Constructs a number for the filter API from the given parameter. Can also be used on the values returned from - * for DateTime values. To create a filter with a date, use dh.DateWrapper.ofJsDate or - * dh.i18n.DateTimeFormat.parse. To create a filter with a 64-bit long integer, use - * dh.LongWrapper.ofString. + * {@link io.deephaven.web.client.api.TableData.Row#get(TableData.RowPositionUnion)} for DateTime values. To create + * a filter with a date, use dh.DateWrapper.ofJsDate or + * {@link io.deephaven.web.client.api.i18n.JsDateTimeFormat#parse(String, JsTimeZone)}. To create a filter with a + * 64-bit long integer, use {@link LongWrapper#ofString(String)}. * - * @param input - * @return + * @param input the number to wrap as a FilterValue + * @return an immutable FilterValue that can be built into a filter */ public static FilterValue ofNumber(OfNumberUnionParam input) { Objects.requireNonNull(input); diff --git a/web/client-api/src/main/java/io/deephaven/web/client/api/tree/JsTreeTable.java b/web/client-api/src/main/java/io/deephaven/web/client/api/tree/JsTreeTable.java index 18ae065378f..d6559d3bb92 100644 --- a/web/client-api/src/main/java/io/deephaven/web/client/api/tree/JsTreeTable.java +++ b/web/client-api/src/main/java/io/deephaven/web/client/api/tree/JsTreeTable.java @@ -71,39 +71,44 @@ import static io.deephaven.web.client.api.subscription.ViewportData.NO_ROW_FORMAT_COLUMN; /** - * Behaves like a JsTable externally, but data, state, and viewports are managed by an entirely different mechanism, and - * so reimplemented here. - * + * Behaves like a {@link JsTable} externally, but data, state, and viewports are managed by an entirely different + * mechanism, and so reimplemented here. + *

* Any time a change is made, we build a new request and send it to the server, and wait for the updated state. - * + *

* Semantics around getting updates from the server are slightly different - we don't "unset" the viewport here after * operations are performed, but encourage the client code to re-set them to the desired position. - * + *

* The table size will be -1 until a viewport has been fetched. - * + *

* Similar to a table, a Tree Table provides access to subscribed viewport data on the current hierarchy. A different * Row type is used within that viewport, showing the depth of that node within the tree and indicating details about - * whether or not it has children or is expanded. The Tree Table itself then provides the ability to change if a row is + * whether it has children or is expanded. The Tree Table itself then provides the ability to change if a row is * expanded or not. Methods used to control or check if a row should be expanded or not can be invoked on a TreeRow * instance, or on the number of the row (thus allowing for expanding/collapsing rows which are not currently visible in * the viewport). - * - * Events and viewports are somewhat different than tables, due to the expense of computing the expanded/collapsed rows + *

+ * Events and viewports are somewhat different from tables, due to the expense of computing the expanded/collapsed rows * and count of children at each level of the hierarchy, and differences in the data that is available. - * - * - There is no totalSize property. - The viewport is not un-set when changes are made to filter or sort, but - * changes will continue to be streamed in. It is suggested that the viewport be changed to the desired position - * (usually the first N rows) after any filter/sort change is made. Likewise, getViewportData() will always - * return the most recent data, and will not wait if a new operation is pending. - Custom columns are not directly - * supported. If the TreeTable was created client-side, the original Table can have custom columns applied, and - * the TreeTable can be recreated. - The totalsTableConfig property is instead a method, and returns a - * promise so the config can be fetched asynchronously. - Totals Tables for trees vary in behavior between hierarchical - * tables and roll-up tables. This behavior is based on the original flat table used to produce the Tree Table - for a - * hierarchical table (i.e. Table.treeTable in the query config), the totals will include non-leaf nodes (since they are - * themselves actual rows in the table), but in a roll-up table, the totals only include leaf nodes (as non-leaf nodes - * are generated through grouping the contents of the original table). Roll-ups also have the - * isIncludeConstituents property, indicating that a Column in the tree may have a constituentType - * property reflecting that the type of cells where hasChildren is false will be different from usual. + *

+ *

    + *
  • There is no {@link JsTable#getTotalSize() totalSize} property.
    • + *
  • The viewport is not un-set when changes are made to filter or sort, but changes will continue to be streamed in. + * It is suggested that the viewport be changed to the desired position (usually the first N rows) after any filter/sort + * change is made. Likewise, getViewportData() will always return the most recent data, and will not wait if a new + * operation is pending.
    • + *
  • Custom columns are not directly supported. If the TreeTable was created client-side, the original Table can have + * custom columns applied, and the TreeTable can be recreated.
    • + *
  • The {@link JsTable#getTotalsTableConfig()} property is instead a method, {@link #getTotalsTableConfig()}, and + * returns a promise so the config can be fetched asynchronously.
    • + *
  • Totals Tables for trees vary in behavior between tree tables and roll-up tables. This behavior is based on the + * original flat table used to produce the Tree Table - for a hierarchical table (i.e. Table.treeTable in the query + * config), the totals will include non-leaf nodes (since they are themselves actual rows in the table), but in a + * roll-up table, the totals only include leaf nodes (as non-leaf nodes are generated through grouping the contents of + * the original table). Roll-ups also have the {@link JsRollupConfig#includeConstituents} property, indicating that a + * {@link Column} in the tree may have a {@link Column#getConstituentType()} property reflecting that the type of cells + * where {@link TreeRow#hasChildren()} is false will be different from usual.
    • + *
*/ @JsType(namespace = "dh", name = "TreeTable") public class JsTreeTable extends HasLifecycle implements ServerObject {