From 8cb5a51aa77d6db5cce44273b7722543d38619a6 Mon Sep 17 00:00:00 2001 From: Dean Herbert Date: Wed, 15 Feb 2023 15:14:38 +0900 Subject: [PATCH] Add further documentation to skin classes --- osu.Game/Skinning/ISkin.cs | 2 +- osu.Game/Skinning/ISkinComponentLookup.cs | 3 ++- osu.Game/Skinning/ISkinSource.cs | 10 +++++++++- osu.Game/Skinning/ISkinnableDrawable.cs | 4 ++-- osu.Game/Skinning/SerialisedDrawableInfo.cs | 3 ++- osu.Game/Skinning/SkinProvidingContainer.cs | 7 ++++++- osu.Game/Skinning/SkinReloadableDrawable.cs | 3 ++- osu.Game/Skinning/SkinTransformer.cs | 7 +++++++ 8 files changed, 31 insertions(+), 8 deletions(-) diff --git a/osu.Game/Skinning/ISkin.cs b/osu.Game/Skinning/ISkin.cs index 45be5582f6..fa04dda202 100644 --- a/osu.Game/Skinning/ISkin.cs +++ b/osu.Game/Skinning/ISkin.cs @@ -10,7 +10,7 @@ using osu.Game.Audio; namespace osu.Game.Skinning { /// - /// Provides access to skinnable elements. + /// Provides access to various elements contained by a skin. /// public interface ISkin { diff --git a/osu.Game/Skinning/ISkinComponentLookup.cs b/osu.Game/Skinning/ISkinComponentLookup.cs index be4043d7cf..25ee086707 100644 --- a/osu.Game/Skinning/ISkinComponentLookup.cs +++ b/osu.Game/Skinning/ISkinComponentLookup.cs @@ -4,7 +4,8 @@ namespace osu.Game.Skinning { /// - /// A lookup type which can be used with . + /// The base lookup type to be used with . + /// Should be implemented as necessary to add further criteria to lookups, which are usually consumed by ruleset transformers or legacy lookup cases. /// /// /// Implementations of should match on types implementing this interface diff --git a/osu.Game/Skinning/ISkinSource.cs b/osu.Game/Skinning/ISkinSource.cs index 89f656a12c..b05d52d47c 100644 --- a/osu.Game/Skinning/ISkinSource.cs +++ b/osu.Game/Skinning/ISkinSource.cs @@ -7,8 +7,16 @@ using System.Collections.Generic; namespace osu.Game.Skinning { /// - /// Provides access to skinnable elements. + /// An abstract skin implementation which generally provides access to more than one skins (with fallback logic). /// + /// + /// Common usage is to do an initial lookup via , and use the returned + /// 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 methods like + /// directly). + /// public interface ISkinSource : ISkin { /// diff --git a/osu.Game/Skinning/ISkinnableDrawable.cs b/osu.Game/Skinning/ISkinnableDrawable.cs index 5ec2fa0f43..48f5b91c29 100644 --- a/osu.Game/Skinning/ISkinnableDrawable.cs +++ b/osu.Game/Skinning/ISkinnableDrawable.cs @@ -10,13 +10,13 @@ using osu.Game.Configuration; namespace osu.Game.Skinning { /// - /// 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. /// /// /// Attaching this interface to any will make it serialisable to user skins (see ). /// Adding annotated bindables will also allow serialising settings automatically. /// - /// Serialisation is done via using . + /// Serialisation is done via using . /// public interface ISkinnableDrawable : IDrawable { diff --git a/osu.Game/Skinning/SerialisedDrawableInfo.cs b/osu.Game/Skinning/SerialisedDrawableInfo.cs index 8bcfed1dbc..90762da011 100644 --- a/osu.Game/Skinning/SerialisedDrawableInfo.cs +++ b/osu.Game/Skinning/SerialisedDrawableInfo.cs @@ -18,7 +18,8 @@ using osuTK; namespace osu.Game.Skinning { /// - /// Serialised information governing custom changes to an . + /// Serialised backing data for s. + /// Used for json serialisation in user skins. /// [Serializable] public sealed class SerialisedDrawableInfo diff --git a/osu.Game/Skinning/SkinProvidingContainer.cs b/osu.Game/Skinning/SkinProvidingContainer.cs index afead7b072..2612e0b47c 100644 --- a/osu.Game/Skinning/SkinProvidingContainer.cs +++ b/osu.Game/Skinning/SkinProvidingContainer.cs @@ -15,8 +15,13 @@ using osu.Game.Audio; namespace osu.Game.Skinning { /// - /// A container which adds a local to the hierarchy. + /// A container which adds a provided to the DI skin lookup hierarchy. /// + /// + /// This container will expose an to its children. + /// The source will first consider the skin provided via the constructor (if any), then fallback + /// to any providers in the parent DI hierarchy. + /// public partial class SkinProvidingContainer : Container, ISkinSource { public event Action? SourceChanged; diff --git a/osu.Game/Skinning/SkinReloadableDrawable.cs b/osu.Game/Skinning/SkinReloadableDrawable.cs index 1c947a4a84..cef1db4bc0 100644 --- a/osu.Game/Skinning/SkinReloadableDrawable.cs +++ b/osu.Game/Skinning/SkinReloadableDrawable.cs @@ -9,7 +9,8 @@ using osu.Framework.Graphics.Pooling; namespace osu.Game.Skinning { /// - /// A drawable which has a callback when the skin changes. + /// A poolable drawable implementation which has a pre-wired callback (see ) that fires + /// once on load and again on any subsequent skin change. /// public abstract partial class SkinReloadableDrawable : PoolableDrawable { diff --git a/osu.Game/Skinning/SkinTransformer.cs b/osu.Game/Skinning/SkinTransformer.cs index e05961d404..ed5b04da1e 100644 --- a/osu.Game/Skinning/SkinTransformer.cs +++ b/osu.Game/Skinning/SkinTransformer.cs @@ -10,6 +10,13 @@ using osu.Game.Audio; namespace osu.Game.Skinning { + /// + /// A default skin transformer, which falls back to the provided skin by default. + /// + /// + /// Implementations of skin transformers should generally derive this class and override + /// individual lookup methods, modifying the lookup flow as required. + /// public abstract class SkinTransformer : ISkinTransformer { public ISkin Skin { get; }