Xiao-zhen-Liu commented on PR #5043:
URL: https://github.com/apache/texera/pull/5043#issuecomment-4501667945
@carloea2 one more pass before merging: the new code (parser service, sync
service, and component) has very little documentation beyond the license
header. For a foundation PR that PRs #2 to #4 will build on top of, the public
contracts need to be readable without diving into method bodies. Please add
JSDoc on:
**Parser service**
- The `UiUdfParametersParserService` class (one or two sentences on what it
does and when to use it).
- `parse(code)`: what it accepts, what it returns, and the conditions under
which it throws `UiUdfParametersParseError`.
- The exported `UiUdfParameter` type and the `UiUdfParametersParseError`
class.
**Sync service**
- The `UiUdfParametersSyncService` class.
- `uiParametersChanged$` and `uiParametersParseError$`: what each one emits,
when, and (for the error stream) how subscribers should interpret a `{
operatorId, message: undefined }` event.
- `attachToYCode(operatorId, yCode)`: the lifecycle, the meaning of the
returned cleanup function, and whether it is safe to call more than once for
the same operator.
- `syncStructureFromCode(operatorId, codeFromEditor?)`: the precondition
(operator must be a Python UDF, code must be defined) and what the consumer is
expected to do when an event is emitted.
- A short note next to `UI_PARAMETER_SYNC_DEBOUNCE_TIME_MS = 200` explaining
the reasoning, so the value is not changed later without that context.
**Component**
- The `UiUdfParametersComponent` class (one sentence on what it renders).
- `getColumnField` and `configureDisabledState` (one line each, since these
are the only non-trivial surfaces).
The bodies are well-written and not hard to follow, but the next person
extending this code should not have to read every function to understand what
each promises. This does not need to be exhaustive: one or two sentences per
public surface is enough.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
