Update ReloadAttribute documentation and linked documentation

Update Documentation for ReloadAttribute and linked ReloadGroupAttribute and ResourceReloader in RPCore package.

Packages/com.unity.render-pipelines.core/Runtime/Common/ReloadAttribute.cs

@@ -3,11 +3,52 @@
 namespace UnityEngine.Rendering
 {
     /// <summary>
-    /// Attribute specifying information to reload with <see cref="ResourceReloader"/>. This is only
-    /// used in the editor and doesn't have any effect at runtime.
+    /// The <see cref="ReloadAttribute"/> attribute specifies paths for loading or reloading resources and has no direct action.
+    /// Used with the <see cref="ResourceReloader"/> to define where to load data for null fields.
     /// </summary>
+    /// <remarks>
+    /// This attribute is designed for use in the Unity Editor and has no effect at runtime.
+    /// 
+    /// <see cref="IRenderPipelineResources"/> have their own attribute <see cref="ResourcePathAttribute"/> to do this.
+    /// When using them, resource reloading is handled automatically by the engine and does not require calling ResourceReloader.
+    /// 
+    /// While ResourceReloader was originally created for handling Scriptable Render Pipeline (SRP) resources, it has been replaced by <see cref="IRenderPipelineResources"/>.
+    /// The <see cref="ResourceReloader"/>, <see cref="ResourceReloader"/> and <see cref="ReloadGroupAttribute"/> remain available for for user-defined assets.
+    /// </remarks>
     /// <seealso cref="ResourceReloader"/>
     /// <seealso cref="ReloadGroupAttribute"/>
+    /// <example>
+    /// <para> This shows how to use the attribute in the expected scenario. This is particularly useful for content creators.
+    /// Adding a new field to a class that defines an asset results in null values for existing instances missing the field in their serialized data. Therefore, when a new field is added, a system for reloading null values may be necessary. </para>
+    /// <code>
+    ///using UnityEngine;
+    ///using UnityEditor;
+    ///
+    ///public class MyResourcesAsset : ScriptableObject
+    ///{
+    ///    [Reload("Shaders/Blit.shader")]
+    ///    public Shader blit;
+    ///    
+    ///    // Added in version 2
+    ///    [Reload("Shaders/betterBlit.shader")]
+    ///    public Shader betterBlit;
+    ///}
+    ///
+    ///public static class MyResourceHandler
+    ///{
+    ///    public static MyResourcesAsset GetAndReload()
+    ///    {
+    ///        var resources = AssetDatabase.LoadAssetAtPath&lt;MyResourcesAsset&gt;("MyResources.asset");
+    ///
+    ///        // Ensure that update of the data layout of MyResourcesAsset
+    ///        // will not result in null value for asset already existing.
+    ///        // (e.g.: added betterBlit in the case above)
+    ///        ResourceReloader.ReloadAllNullIn(resources, "Packages/com.my-custom-package/");
+    ///        return resources;
+    ///    }
+    ///}
+    /// </code>
+    /// </example>
     [AttributeUsage(AttributeTargets.Field)]
     public sealed class ReloadAttribute : Attribute
     {
@@ -52,6 +93,23 @@ public enum Package
         /// </summary>
         /// <param name="paths">Search paths</param>
         /// <param name="package">The lookup method</param>
+        /// <example>
+        /// <para> This example demonstrates how to handle arrays with different resource paths. </para>
+        /// <code>
+        ///using UnityEngine;
+        ///
+        ///public class MyResourcesAsset : ScriptableObject
+        ///{
+        ///    [ResourcePaths(new[]
+        ///    {
+        ///        "Texture/FilmGrain/Thin.png",
+        ///        "Texture/FilmGrain/Medium.png",
+        ///        "Texture/FilmGrain/Large.png",
+        ///    })]
+        ///    public Texture[] filmGrains;
+        ///}
+        /// </code>
+        /// </example>
         public ReloadAttribute(string[] paths, Package package = Package.Root)
         {
 #if UNITY_EDITOR
@@ -65,6 +123,18 @@ public ReloadAttribute(string[] paths, Package package = Package.Root)
         /// </summary>
         /// <param name="path">Search path</param>
         /// <param name="package">The lookup method</param>
+        /// <example>
+        /// <para> This example shows how to directly specify the path of an asset. </para>
+        /// <code>
+        ///using UnityEngine;
+        ///
+        ///public class MyResourcesAsset : ScriptableObject
+        ///{
+        ///    [Reload("Shaders/Blit.shader")]
+        ///    public Shader blit;
+        ///}
+        /// </code>
+        /// </example>
         public ReloadAttribute(string path, Package package = Package.Root)
             : this(new[] { path }, package)
         { }
@@ -77,6 +147,22 @@ public ReloadAttribute(string path, Package package = Package.Root)
         /// <param name="rangeMin">The array start index (inclusive)</param>
         /// <param name="rangeMax">The array end index (exclusive)</param>
         /// <param name="package">The lookup method</param>
+        /// <example>
+        /// <para> This example demonstrates handling arrays with resource paths that share a common format, differing only by an index. </para>
+        /// <code>
+        ///using UnityEngine;
+        ///
+        ///public class MyResourcesAsset : ScriptableObject
+        ///{
+        ///    // The following will seek for resources:
+        ///    //  - Texture/FilmGrain/Thin1.png
+        ///    //  - Texture/FilmGrain/Thin2.png
+        ///    //  - Texture/FilmGrain/Thin3.png
+        ///    [ResourcePaths("Texture/FilmGrain/Thin{0}.png", 1, 4)]
+        ///    public Texture[] thinGrains;
+        ///}
+        /// </code>
+        /// </example>
         public ReloadAttribute(string pathFormat, int rangeMin, int rangeMax,
             Package package = Package.Root)
         {

Packages/com.unity.render-pipelines.core/Runtime/Common/ReloadGroupAttribute.cs

@@ -1,14 +1,57 @@
 using System;
+using UnityEditor;
+using static UnityEngine.Rendering.DebugUI.Table;
 
 namespace UnityEngine.Rendering
 {
     /// <summary>
-    /// Attribute specifying that it contains element that should be reloaded.
-    /// If the instance of the class is null, the system will try to recreate
-    /// it with the default constructor.
-    /// Be sure classes using it have default constructor!
+    /// Attribute specifying that fields of this type should be inspected in depth by the <see cref="ResourceReloader"/>. 
+    /// If the associated class instance is null, the system attempts to recreate it using its default constructor.
     /// </summary>
+    /// <remarks>
+    /// Make sure classes using it have a default constructor!
+    /// </remarks>
+    /// <seealso cref="ResourceReloader"/>
     /// <seealso cref="ReloadAttribute"/>
+    /// <example>
+    /// <para> This shows how to use the attribute in the expected scenario. This is particularly useful for content creators.
+    /// Adding a new field to a class that defines an asset results in null values for existing instances missing the field in their serialized data. Therefore, when a new field is added, a system for reloading null values may be necessary. </para>
+    /// <code>
+    ///using UnityEngine;
+    ///using UnityEditor;
+    ///
+    ///[ReloadGroup]
+    ///public class MyShaders
+    ///{
+    ///    [Reload("Shaders/Blit.shader")]
+    ///    public Shader blit;
+    ///}
+    ///
+    ///public class MyResourcesAsset : ScriptableObject
+    ///{
+    ///    // Object used for contextualizing would resolve to be null in already existing
+    ///    // instance of MyResourcesAsset that already exists.
+    ///    public MyShaders shaders;
+    ///
+    ///    [Reload("Textures/BayerMatrix.png")]
+    ///    public Texture2D bayerMatrixTex;
+    ///}
+    ///
+    ///public static class MyResourceHandler
+    ///{
+    ///    public static MyResourcesAsset GetAndReload()
+    ///    {
+    ///        var resources = AssetDatabase.LoadAssetAtPath&lt;MyResourcesAsset&gt;("MyResources.asset");
+    ///
+    ///        // Ensure that update of the data layout of MyResourcesAsset
+    ///        // will not result in null value for asset already existing.
+    ///        // (e.g.: adding new field in MyResourcesAsset or MyShaders classes)
+    ///        ResourceReloader.ReloadAllNullIn(resources, "Packages/com.my-custom-package/");
+    ///        return resources;
+    ///    }
+    ///}
+    /// </code>
+    /// </example>
     [AttributeUsage(AttributeTargets.Class)]
     public sealed class ReloadGroupAttribute : Attribute
     { }

Packages/com.unity.render-pipelines.core/Runtime/Utilities/ResourceReloader.cs

@@ -15,12 +15,14 @@ namespace UnityEngine.Rendering
     /// The reload call should only be done in Editor context though but it
     /// could be called from runtime entities.
     /// </summary>
+    /// <seealso cref="ReloadAttribute"/>
+    /// <seealso cref="ReloadGroupAttribute"/>
     public static class ResourceReloader
     {
         /// <summary>
         /// Looks for resources in the given <paramref name="container"/> object and reload the ones
-        /// that are missing or broken.
-        /// This version will still return null value without throwing error if the issue is due to
+        /// that are missing or broken, using the <see cref="ReloadAttribute"/> to find the paths.
+        /// This version returns a null value without throwing an error if the issue is
         /// AssetDatabase being not ready. But in this case the assetDatabaseNotReady result will be true.
         /// </summary>
         /// <param name="container">The object containing reload-able resources</param>
@@ -47,7 +49,8 @@ public static (bool hasChange, bool assetDatabaseNotReady) TryReloadAllNullIn(Sy
 
         /// <summary>
         /// Looks for resources in the given <paramref name="container"/> object and reload the ones
-        /// that are missing or broken.
+        /// that are missing or broken, using the <see cref="ReloadAttribute"/> to find the paths.
+        /// See <see cref="ReloadAttribute"/> for an example.
         /// </summary>
         /// <param name="container">The object containing reload-able resources</param>
         /// <param name="basePath">The base path for the package</param>