Document IOTypeOptions

[pixelzoom]

I'm trying to create an IOType in equality-explorer. I'm trying to understand the supertype options. And it doesn't help that not a single option for IOType is properly documented. Did we not agree to document options in their type definitions?

From IOType.ts:

type MainOptions = {
  supertype?: IOType | null;
  events?: string[];
  dataDefaults?: Record<string, unknown>;
  metadataDefaults?: Partial<PhetioObjectMetadata>;
  documentation?: string;
  methods?: Record<string, IOTypeMethod>;
  methodOrder?: string[];
  parameterTypes?: IOType[];
  isFunctionType?: boolean;
};
...
type StateOptions<T, StateType> = {

  // Should be required, but sometimes this is only in the parent IOType, like in DerivedPropertyIO
  stateSchema?: StateSchemaOption<T, StateType>;
  toStateObject?: ( t: T ) => StateType;

  // If it is serializable, then it is optionally deserializable via one of these methods
  fromStateObject?: ( s: StateType ) => T;
  stateToArgsForConstructor?: ( s: StateType ) => unknown[];
  applyState?: ( t: T, state: StateType ) => void;
  defaultDeserializationMethod?: DeserializationType;
  addChildElement?: AddChildElement;
} | {

  // Otherwise it cannot have any stateful parts
  toStateObject?: never;
  stateSchema?: never;
  fromStateObject?: never;
  stateToArgsForConstructor?: never;
  applyState?: never;
  defaultDeserializationMethod?: never;
  addChildElement?: never;
};

[pixelzoom]

This continues to be a problem. I'm running into it again today in https://github.com/phetsims/beers-law-lab/issues/265, where I'm trying to understand the implications of the supertype option. There is zero documentation for IOTypeOptions.supertype AND IOType.supertype.

[pixelzoom]

Now I'm wrestling with option stateSchema. Here's the entire documentation in IOType.ts:

  // Should be required, but sometimes this is only in the parent IOType, like in DerivedPropertyIO
  stateSchema?: StateSchemaOption<T, StateType>;
...
  // The schema for how this IOType is serialized. Just for this level in the IOType hierarchy,
  // see getAllStateSchema().
  public readonly stateSchema: StateSchema<T, StateType>;

This documentation is not at all useful or helpful -- especially since it says "see getAllStateSchema", and that method does not exist.

[samreid]

In the commits, I completed the following:

• Simplified the options by combining and reducing them
• Added documentation for options.supertype
• Moved documentation from the constructor to the options. This also helped with the state schema options documentation.

@pixelzoom can you please review?

[pixelzoom]

Thanks, this is much more helpful. I skimmed the commits - I didn't read every comment for every option. I'll plan to read them as I need them.

Closing.