meta: added meta_any::ref as an alias to meta_any operator* (close #479)

TODO

@@ -17,10 +17,10 @@
   - get -> all, exclude -> none
 
 Next:
-* replace observer class with observer functions
+* add observer functions aside observer class
 * get(cmp, entity) -> void *, set(cmp, entity, void *)
 * review multi component views to reduce instantiations once empty types are gone...
-* move signals down to the storage class?
+* describe how to hook into the type system to eg auto-generate meta types on first use
 
 * WIP:
  - introduce the component iterators for non-contiguous collections of entities (multi component views, observers, user defined collections)

docs/md/meta.md

@@ -231,16 +231,26 @@ In other words, whenever `meta_any` intercepts a `reference_wrapper`, it acts as
 a reference to the original instance rather than making a copy of it. The
 contained object is never destroyed and users must ensure that its lifetime
 exceeds that of the container.<br/>
-Similarly, to create a copy that works as a light reference for the managed
-object, it's possible to dereference a given `meta_any`:
+Similarly, to create a copy that works as a _light_ reference for the managed
+object, it's possible to _dereference_ a given `meta_any` so as to invoke its
+aliasing constructor:
 
 ```cpp
+// aliasing constructor
+entt::meta_any ref = any.ref();
+```
+
+This is also equivalent to:
+
+```cpp
+// indirection operator
 entt::meta_any ref = *any;
 ```
 
-It doesn't matter if the starting container actually holds an object or acts as
-a reference for unmanaged elements, the new instance thus created won't create
-copies and will only serve as a reference for the original item.<br/>
+In both cases, it doesn't matter if the starting container actually holds an
+object or acts as a reference for unmanaged elements, the new instance thus
+created won't create copies and will only serve as a reference for the original
+item.<br/>
 It means that, starting from the example above, both `ref` and` any` will point
 to the same object, whether it's initially contained in `any` or already an
 unmanaged one. This is particularly useful for passing instances of `meta_any`

src/entt/meta/meta.hpp

@@ -565,12 +565,20 @@ public:
         *this = meta_any{std::in_place_type_t<Type>{}, std::forward<Args>(args)...};
     }
 
+    /**
+     * @brief Aliasing constructor.
+     * @return A meta any that shares a reference to an unmanaged object.
+     */
+    meta_any ref() const ENTT_NOEXCEPT {
+        return meta_any{node, instance};
+    }
+
     /**
      * @brief Indirection operator for aliasing construction.
-     * @return An alias to the contained object.
+     * @return A meta any that shares a reference to an unmanaged object.
      */
     meta_any operator *() const ENTT_NOEXCEPT {
-        return meta_any{node, instance};
+        return ref();
     }
 
     /**
@@ -631,7 +639,7 @@ private:
  *
  * A handle doesn't perform copies and isn't responsible for the contained
  * object. It doesn't prolong the lifetime of the pointed instance.<br/>
- * Handles are used mainly to generate aliases for actual objects when needed.
+ * Handles are used to generate meta references to actual objects when needed.
  */
 struct meta_handle {
     /*! @brief Default constructor. */
@@ -640,7 +648,7 @@ struct meta_handle {
     {}
 
     /**
-     * @brief Creates an alias for the actual object.
+     * @brief Creates a handle that points to an unmanaged object.
      * @tparam Type Type of object to use to initialize the container.
      * @param value An instance of an object to use to initialize the container.
      */