particle type doc confusing

[jim-obrien-orig]

The ParticleType docs are unnecessarily confusing. They're well written, but I think the reliance on the atom analogy and trying to fit the constraint machine into that analogy may be part of what is creating the confusion. But there are also other word choices and capitalization choices that are causing problems as well (especially to a Java developer).

I had to read several times back-and-forth between the constraint machine page and the particle type page to realize that the particle type is really just the state machine definition. The particle type is apparently the class or definition, and the instance is an instance of the state machine. I think the word "Type" may not be the best choice, and when something is capitalized with camel-case, in java-land this seems like a pre-defined Interface, class or Enum. Both ParicleType and ParticleInstance are capitalized, causing me to look for them in the cliend sdk. I got confused when I couldn't find them.

Immediately the next paragraph jumps to quarks and says they're part of particle types, but I still don't know what particle types are at that point. The quarks section is very unclear Are those the limited states that something can pass between? Or are they the type of possible state transitions? Are those the only types possible?
The example that follows has nothing to do with the four quarks just mentioned. (I found out while going through the subclasses of Particle that the quarks are interfaces.) Only when seeing the capitalization of MyParticle did the bell ring that ParticleType was a class and ParticleInstance and instance of that class, and both were really just Particles.

Constraint Scrypt - I'm not sure we really want to imply another scripting language like solidity? This is a javascript example I'm assuming. In addition, it implied to me that the constraint machine system is controlled by magic "scrypts: outside of the normal sdk-driven radix echosystem. It took me a while - and I'm assuming I'm correct, that you write d'app utilizing the constraint machine in any language that has a Radix sdk.

"User-Defined Particle Types" - the last paragraph is hard to understand as well. You can't define particle types? They are already defined? Where? Again, I looked through the SDK and couldn't find ParticleTypes defined anywhere. Going through the beta-1.003 code, I see several defined sub-classes of Particle. Those appear to be the only ParticleTypes allowed, but they are marked public not public final or protected final. And just because that's all that's in the Java sdk, that doesn't mean the sdk is missing some types that the java-sdk hasn't implemented wrapper classes to. Where's the canonical source of truth for particle types in an open-api type spec that is pointed to for reference?

If you can't define particle types, what can you do? If a "particle type" represents a constraint or state machine definition, and they you are limited to a predefined set, then it appears you can't build your own state machine? How do you build a d'App? Why the example above? I'm assuming this is developer documentation. In that case, it isn't the usual practice to show examples of what you can't build and not show examples of what you can build. I understand the impulse of not wanting to give the impression that the feature is limited to its current implementation, but there are other ways of managing that in documentation.

I may write an issue about the corresponding constraint machine page as well.