updated doc

docs/md/resource.md

@@ -84,7 +84,7 @@ my_resource_cache cache{};
 ```
 
 The idea is to create different caches for different types of resources and to
-manage each one independently and in the most appropriate way.<br/>
+manage each one independently in the most appropriate way.<br/>
 As a (very) trivial example, audio tracks can survive in most of the scenes of
 an application while meshes can be associated with a single scene and then
 discarded when users leave it.
@@ -103,7 +103,7 @@ const auto empty = cache.empty();
 cache.clear();
 ```
 
-Besides these member functions, it contains what is needed to load, use and
+Besides these member functions, a cache contains what is needed to load, use and
 discard resources of the given type.<br/>
 Before to explore this part of the interface, it makes sense to mention how
 resources are identified. The type of the identifiers to use is defined as:
@@ -122,7 +122,7 @@ constexpr auto identifier = entt::resource_cache<resource>::resource_type{"my/re
 constexpr auto hs = entt::hashed_string{"my/resource/identifier"};
 ```
 
-The class `hashed_string` is described in a dedicated section, so I won't do in
+The class `hashed_string` is described in a dedicated section, so I won't go in
 details here.
 
 Resources are loaded and thus stored in a cache through the `load` member
@@ -137,20 +137,18 @@ cache.load<my_loader>(identifier, 0);
 cache.load<my_loader>("another/identifier"_hs, 42);
 ```
 
-The return value can be used to know if the resource has been loaded correctly.
-In case the loader returns an invalid pointer or the resource already exists in
-the cache, a false value is returned:
+The function returns a handle to the resource, whether it already exists or is
+loaded. In case the loader returns an invalid pointer, the handle is invalid as
+well and therefore it can be easily used with an `if` statement:
 
 ```cpp
-if(!cache.load<my_loader>("another/identifier"_hs, 42)) {
+if(auto handle = cache.load<my_loader>("another/identifier"_hs, 42); handle) {
     // ...
 }
 ```
 
-Unfortunately, in this case there is no way to know what was the problem
-exactly. However, before trying to load a resource or after an error, one can
-use the `contains` member function to know if a cache already contains a
-specific resource:
+Before trying to load a resource, the `contains` member function can be used to
+know if a cache already contains a specific resource:
 
 ```cpp
 auto exists = cache.contains("my/identifier"_hs);
@@ -160,13 +158,11 @@ There exists also a member function to use to force a reload of an already
 existing resource if needed:
 
 ```cpp
-auto result = cache.reload<my_loader>("another/identifier"_hs, 42);
+auto handle = cache.reload<my_loader>("another/identifier"_hs, 42);
 ```
 
-As above, the function returns true in case of success, false otherwise. The
-sole difference in this case is that an error necessarily means that the loader
-has failed for some reasons to load the resource.<br/>
-Note that the `reload` member function is a kind of alias of the following
+As above, the function returns a handle to the resource that is invalid in case
+of errors. The `reload` member function is a kind of alias of the following
 snippet:
 
 ```cpp
@@ -175,11 +171,11 @@ cache.load<my_loader>(identifier, 42);
 ```
 
 Where the `discard` member function is used to get rid of a resource if loaded.
-In case the cache doesn't contain a resource for the given identifier, the
-function does nothing and returns immediately.
+In case the cache doesn't contain a resource for the given identifier, `discard`
+does nothing and returns immediately.
 
 So far, so good. Resources are finally loaded and stored within the cache.<br/>
-They are returned to users in the form of handles. To get one of them:
+They are returned to users in the form of handles. To get one of them later on:
 
 ```cpp
 auto handle = cache.handle("my/identifier"_hs);
@@ -187,10 +183,10 @@ auto handle = cache.handle("my/identifier"_hs);
 
 The idea behind a handle is the same of the flyweight pattern. In other terms,
 resources aren't copied around. Instead, instances are shared between handles.
-Users of a resource owns a handle and it guarantees that a resource isn't
-destroyed until all the handles are destroyed, even if the resource itself is
-removed from the cache.<br/>
-Handles are tiny objects both movable and copyable. They returns the contained
+Users of a resource own a handle that guarantees that a resource isn't destroyed
+until all the handles are destroyed, even if the resource itself is removed from
+the cache.<br/>
+Handles are tiny objects both movable and copyable. They return the contained
 resource as a const reference on request:
 
 * By means of the `get` member function:
@@ -229,13 +225,14 @@ if(handle) {
 Finally, in case there is the need to load a resource and thus to get a handle
 without storing the resource itself in the cache, users can rely on the `temp`
 member function template.<br/>
-The declaration is similar to the one of `load` but for the fact that it doesn't
-require a resource identifier and it doesn't return a boolean value. Instead,
-it returns a (possibly invalid) handle for the resource:
+The declaration is similar to that of `load`, a (possibly invalid) handle for
+the resource is returned also in this case:
 
 ```cpp
-auto handle = cache.temp<my_loader>(42);
+if(auto handle = cache.temp<my_loader>(42); handle) {
+    // ...
+}
 ```
 
-Do not forget to test the handle for validity. Otherwise, getting the reference
-to the resource it points may result in undefined behavior.
+Do not forget to test the handle for validity. Otherwise, getting a reference to
+the resource it points may result in undefined behavior.