bevy_reflect: Replace "value" terminology with "opaque"

[MrGVSV]

Objective

Currently, the term "value" in the context of reflection is a bit overloaded.

For one, it can be used synonymously with "data" or "variable". An example sentence would be "this function takes a reflected value".

However, it is also used to refer to reflected types which are ReflectKind::Value. These types are usually either primitives, opaque types, or types that don't fall into any other ReflectKind (or perhaps could, but don't due to some limitation/difficulty). An example sentence would be "this function takes a reflected value type".

This makes it difficult to write good documentation or other learning material without causing some amount of confusion to readers. Ideally, we'd be able to move away from the ReflectKind::Value usage and come up with a better term.

Solution

This PR replaces the terminology of "value" with "opaque" across bevy_reflect. This includes in documentation, type names, variant names, and macros.

The term "opaque" was chosen because that's essentially how the type is treated within the reflection API. In other words, its internal structure is hidden. All we can do is work with the type itself.

Primitives

While primitives are not technically opaque types, I think it's still clearer to refer to them as "opaque" rather than keep the confusing "value" terminology.

We could consider adding another concept for primitives (e.g. ReflectKind::Primitive), but I'm not sure that provides a lot of benefit right now. In most circumstances, they'll be treated just like an opaque type. They would also likely use the same macro (or two copies of the same macro but with different names).

Testing

You can test locally by running:

cargo test --package bevy_reflect --all-features

---

Migration Guide

The reflection concept of "value type" has been replaced with a clearer "opaque type". The following renames have been made to account for this:

• ReflectKind::Value → ReflectKind::Opaque
• ReflectRef::Value → ReflectRef::Opaque
• ReflectMut::Value → ReflectMut::Opaque
• ReflectOwned::Value → ReflectOwned::Opaque
• TypeInfo::Value → TypeInfo::Opaque
• ValueInfo → OpaqueInfo
• impl_reflect_value! → impl_reflect_opaque!
• impl_from_reflect_value! → impl_from_reflect_opaque!

Additionally, declaring your own opaque types no longer uses #[reflect_value]. This attribute has been replaced by #[reflect(opaque)]:

// BEFORE
#[derive(Reflect)]
#[reflect_value(Default)]
struct MyOpaqueType(u32);

// AFTER
#[derive(Reflect)]
#[reflect(opaque)]
#[reflect(Default)]
struct MyOpaqueType(u32);

Note that the order in which #[reflect(opaque)] appears does not matter.

[alice-i-cecile]

On board with the change. Several of the types touched here are missing trait reflection attributes, primarily for Debug. Your call if you want to change it here.

[MrGVSV]

Several of the types touched here are missing trait reflection attributes, primarily for Debug. Your call if you want to change it here.

Done!

[tychedelia]

Calling a primitive opaque is a little surprising, but think this is in general an improvement relative to "value", as it can be argued a primitive has no interior representation. Just one note on minor doc issue.

[soqb]

totally in favour of the direction! i think opaque is a good name but i would also like to suggest Atom as in "indivisible unit" i think it's more slightly descriptive as long as we don't think people will confuse Atoms for atomic values.

[alice-i-cecile]

Hmm, I like both. Opaque makes more sense as an annotation, but Atom feels better for primitives. I'll let y'all bikeshed this for a week, but if a decision is not reached by the next merge train (not today!) I'm going to merge this as is.

[MrGVSV]

totally in favour of the direction! i think opaque is a good name but i would also like to suggest Atom as in "indivisible unit" i think it's more slightly descriptive as long as we don't think people will confuse Atoms for atomic values.

This is pretty good too. Like Alice said, this would help clear up the confusion with primitives.

My only concern is in documentation like you mentioned. We might write "returns an atom type"/"takes an atom value", but readers might see "returns an atomic type"/"takes an atomic value", especially since "atomic" is the adjective form.

For that reason, I think I lean a bit towards "opaque", but I'd love to hear if anyone else has any opinions on the matter! We can definitely go with "atom" if people prefer it.