Bring documentation up to standards in IOType.ts and StateSchema.ts

[pixelzoom]

While working on #282, @samreid and I discovered that documentation for IOType.ts and StateSchema.ts is not up to standards. And that's one of the things that's making IOTypes difficult to use.

For example:

• [x] type documentation in IOType.ts is almost non-existentent. Fields in those types are not documented, which is where fields are supposed to be documented by PhET convention. Some options are not documented at all, e.g. supertype. Some fields are documented where their default value are defined, in the optionize call, which is not where the documentation is supposed to live.

• [x] None of the types defined in StateSchema.ts are documented. defaultApplyState and defaultToStateObject are not documented. asValue is documentation is not at all useful.

• [x] Both IOType and StateSchema refer to "composite schema", and there's even a CompositeSchema type. But I couldn't make any sense of this.

• [x] IOType.ObjectIO is writeable. It should be defined inside the class definition, public static readonly.

[samreid]

Tagging for https://github.com/phetsims/phet-io/issues/1914 and self-unassigning.

[zepumph]

Many updates above. The only thing I didn't do was move the documentation from the options to the field declarations. I think it is clearer in the options definition. Please review.

[pixelzoom]

Much better, thanks. One additional bit of doc in the above commit.

If work is done here, feel free to close.