Renaming & Refactoring

[siefkenj]

This PR primarily introduces new naming conventions with the goal of making it easier for other developers writing components.

The proposed (and included) changes are:

• DependencyInstruction -> DataQuery. A DependencyInstruction is called an Instruction because it instructs Core how to get the data it wants. Another name for this is a query. Query sounds more transparent to me because a developer doesn't really care what core does/how it does it. They just want the answer to their question, which is: "what is the data that satisfies these restrictions?"

• New convention: RequiredData. Suppose we're authoring the Foo state variable. Instead of defining a structure FooDependencies and having FooDependencyInstructions automatically created, a developer creates a private struct RequiredData and RequiredDataGraphQueries is automatically created.

  Motivation: Using a uniform name will make state var files look more similar and will hopefully make them easier to follow, since they will have very similar structures. We also have used the word Dependency for several things. FooDependencies could be interpreted as describing graph queries or as describing the StateVarPointers or as describing the data that has been retrieved by core. Calling it RequiredData makes it clear that it is 1) required for computation, and 2) is data and not pointers/requests.

• dependency_values -> query_results. This could have other names, like required_data_cache or just required_data. This is set after core executes a GraphQuery, so I named it query_results, but this could be a bad name because query_results could be populated by default values (and used before core has done anything?)

• StateVarInterface -> StateVarUpdaters. The trait StateVarInterface defined methods used by core to solicit what data a state var needed, and to trigger it to recompute its data. Updaters is more descriptive than Interface.

• The word Interface has been removed from the General*StateVar structs. It didn't seem to be adding anything.

• General*StateVar structs were renamed *StateVar structs and put in a general_state_var module.

• StateVarReadOnlyView -> StateVarView. Rust convention is that everything is immutable by default and mutable things are distinguished by special words. In general a view should be considered immutable, so we can use the shorter name.

[dqnykamp]

I'm a little worried how BooleanStateVar might be confused with StateVar<bool>. It's interesting how you can BooleanStateVar.into() to get a StateVar<bool>.

I can't decide if this similarity is a good thing so authors just do this naturally, or if it will cause confusion.

[siefkenj]

The nice thing about Rust is that the types are inescapable, so the type information should always be with the developer. We could import them as general_state_var::BooleanStateVar if we really wanted to emphasize it.

[dqnykamp]

Maybe "State variables must cache...", as "expected to" sounds like it might be optional to me.

[siefkenj]

I guess the types might be hard to figure out, but this bit bothered me...it seems like core should cache the results and send them to the component when they're needed...

[dqnykamp]

Yeah, in the Javascript code, core does the caching. I did this solely for the typing, to avoid unwrapping enums on every cycle. Maybe a silly optimization that we can revisit with profiling.

[dqnykamp]

Is this doing something other than reminding us to write tests?

[siefkenj]

No, just a reminder. I almost wrote some tests, but then got distracted...