Add further documentation to skin classes

osu.Game/Skinning/ISkin.cs

@@ -10,7 +10,7 @@ using osu.Game.Audio;
 namespace osu.Game.Skinning
 {
     /// <summary>
-    /// Provides access to skinnable elements.
+    /// Provides access to various elements contained by a skin.
     /// </summary>
     public interface ISkin
     {

osu.Game/Skinning/ISkinComponentLookup.cs

@@ -4,7 +4,8 @@
 namespace osu.Game.Skinning
 {
     /// <summary>
-    /// A lookup type which can be used with <see cref="ISkin.GetDrawableComponent"/>.
+    /// The base lookup type to be used with <see cref="ISkin.GetDrawableComponent"/>.
+    /// Should be implemented as necessary to add further criteria to lookups, which are usually consumed by ruleset transformers or legacy lookup cases.
     /// </summary>
     /// <remarks>
     /// Implementations of <see cref="ISkin.GetDrawableComponent"/> should match on types implementing this interface

osu.Game/Skinning/ISkinSource.cs

@@ -7,8 +7,16 @@ using System.Collections.Generic;
 namespace osu.Game.Skinning
 {
     /// <summary>
-    /// Provides access to skinnable elements.
+    /// An abstract skin implementation which generally provides access to more than one skins (with fallback logic).
     /// </summary>
+    /// <remarks>
+    /// Common usage is to do an initial lookup via <see cref="FindProvider"/>, and use the returned <see cref="ISkin"/>
+    /// to do further lookups for related components.
+    ///
+    /// The initial lookup is used to lock consecutive lookups to the same underlying skin source (as to not get some elements
+    /// from one skin and others from another, which would be the case if using <see cref="ISkin"/> methods like
+    /// <see cref="ISkin.GetSample"/> directly).
+    /// </remarks>
     public interface ISkinSource : ISkin
     {
         /// <summary>

osu.Game/Skinning/ISkinnableDrawable.cs

@@ -10,13 +10,13 @@ using osu.Game.Configuration;
 namespace osu.Game.Skinning
 {
     /// <summary>
-    /// Denotes a drawable which, as a drawable, can be adjusted via skinning specifications.
+    /// A drawable which can be serialised to a skin, placed and customised via the skin layout editor.
     /// </summary>
     /// <remarks>
     /// Attaching this interface to any <see cref="IDrawable"/> will make it serialisable to user skins (see <see cref="SkinImporter.Save"/>).
     /// Adding <see cref="SettingSourceAttribute"/> annotated bindables will also allow serialising settings automatically.
     ///
-    /// Serialisation is done via <see cref="SerialisedDrawableInfo"/> using <see cref="Extensions.DrawableExtensions.CreateSerialisedInfo"/>.
+    /// Serialisation is done via <see cref="SerialisedDrawableInfo"/> using <see cref="osu.Game.Extensions.DrawableExtensions.CreateSerialisedInfo"/>.
     /// </remarks>
     public interface ISkinnableDrawable : IDrawable
     {

osu.Game/Skinning/SerialisedDrawableInfo.cs

@@ -18,7 +18,8 @@ using osuTK;
 namespace osu.Game.Skinning
 {
     /// <summary>
-    /// Serialised information governing custom changes to an <see cref="ISkinnableDrawable"/>.
+    /// Serialised backing data for <see cref="ISkinnableDrawable"/>s.
+    /// Used for json serialisation in user skins.
     /// </summary>
     [Serializable]
     public sealed class SerialisedDrawableInfo

osu.Game/Skinning/SkinProvidingContainer.cs

@@ -15,8 +15,13 @@ using osu.Game.Audio;
 namespace osu.Game.Skinning
 {
     /// <summary>
-    /// A container which adds a local <see cref="ISkinSource"/> to the hierarchy.
+    /// A container which adds a provided <see cref="ISkin"/> to the DI skin lookup hierarchy.
     /// </summary>
+    /// <remarks>
+    /// This container will expose an <see cref="ISkinSource"/> to its children.
+    /// The source will first consider the skin provided via the constructor (if any), then fallback
+    /// to any <see cref="ISkinSource"/> providers in the parent DI hierarchy.
+    /// </remarks>
     public partial class SkinProvidingContainer : Container, ISkinSource
     {
         public event Action? SourceChanged;

osu.Game/Skinning/SkinReloadableDrawable.cs

@@ -9,7 +9,8 @@ using osu.Framework.Graphics.Pooling;
 namespace osu.Game.Skinning
 {
     /// <summary>
-    /// A drawable which has a callback when the skin changes.
+    /// A poolable drawable implementation which has a pre-wired callback (see <see cref="SkinChanged"/>) that fires
+    /// once on load and again on any subsequent skin change.
     /// </summary>
     public abstract partial class SkinReloadableDrawable : PoolableDrawable
     {

osu.Game/Skinning/SkinTransformer.cs

@@ -10,6 +10,13 @@ using osu.Game.Audio;
 
 namespace osu.Game.Skinning
 {
+    /// <summary>
+    /// A default skin transformer, which falls back to the provided skin by default.
+    /// </summary>
+    /// <remarks>
+    /// Implementations of skin transformers should generally derive this class and override
+    /// individual lookup methods, modifying the lookup flow as required.
+    /// </remarks>
     public abstract class SkinTransformer : ISkinTransformer
     {
         public ISkin Skin { get; }