docs improvements

Editor/API/Attributes/BuildPhase.cs

@@ -6,7 +6,17 @@
 
 namespace nadena.dev.ndmf
 {
-    public class BuildPhase
+    /// <summary>
+    /// Build Phases provide a coarse mechanism for grouping passes for execution. Each build phase has a recommended
+    /// usage to help avoid ordering conflicts without needing explicit constraints.
+    ///
+    /// Currently, the following phases are defined:
+    /// - Resolving
+    /// - Generating
+    /// - Transforming
+    /// - Optimizing
+    /// </summary>
+    public sealed class BuildPhase
     {
         public string Name { get; }
 
@@ -16,11 +26,39 @@ internal BuildPhase(string name)
             Name = name;
         }
 
+        /// <summary>
+        /// The resolving phase is intended for use by passes which perform very early processing of components and
+        /// avatar state, before any large-scale changes have been made. For example, Modular Avatar uses this phase
+        /// to resolve string-serialized object passes to their destinations, and to clone animation controllers before
+        /// any changes are made to them.
+        ///
+        /// NDMF also has a built-in phase in Resolving, which removes EditorOnly objects. For more information,
+        /// see nadena.dev.ndmf.builtin.RemoveEditorOnlyPass.
+        /// </summary>
+        /// <see cref="nadena.dev.ndmf.builtin.RemoveEditorOnlyPass"/>
         public static readonly BuildPhase Resolving = new BuildPhase("Resolving");
+
+        /// <summary>
+        /// The generating phase is intended for use by asses which generate components used by later plugins. For
+        /// example, if you want to generate components that will be used by Modular Avatar, this would be the place
+        /// to do it.
+        /// </summary>
         public static readonly BuildPhase Generating = new BuildPhase("Generating");
+
+        /// <summary>
+        /// The transforming phase is intended for general-purpose avatar transformations. Most of Modular Avatar's
+        /// logic runs here.
+        /// </summary>
         public static readonly BuildPhase Transforming = new BuildPhase("Transforming");
+
+        /// <summary>
+        /// The optimizing phase is intended for pure optimizations that need to run late in the build process.
+        /// </summary>
         public static readonly BuildPhase Optimizing = new BuildPhase("Optimizing");
 
+        /// <summary>
+        /// This list contains all built-in phases in the order that they will be executed.
+        /// </summary>
         public static readonly ImmutableList<BuildPhase> BuiltInPhases
             = ImmutableList.Create(Resolving, Generating, Transforming, Optimizing);
 

Editor/API/Attributes/ExportsPlugin.cs

@@ -8,9 +8,13 @@ namespace nadena.dev.ndmf
 {
     /// <summary>
     /// This attribute declares a plugin to be registered with NDMF.
-    /// 
+    ///
     /// <code>
     /// [assembly: ExportsPlugin(typeof(MyPlugin))]
+    ///
+    /// class MyPlugin : Plugin&lt;MyPlugin> {
+    ///   // ...
+    /// }
     /// </code>
     /// </summary>
     [AttributeUsage(AttributeTargets.Assembly)]

Editor/API/Fluent/Sequence/Extensions.cs

@@ -119,6 +119,7 @@ public void WithCompatibleExtension(Type extension, Action<Sequence> action)
         ///   sequence.WithRequiredExtensions(new[] {typeof(foo.bar.MyExtension)}, s => {
         ///     s.Run(typeof(MyPass));
         ///   });
+        /// </code>
         /// </summary>
         /// <param name="extension">The extension to request</param>
         /// <param name="action">An action that will be invoked with the extensions marked required</param>
@@ -145,6 +146,7 @@ public void WithRequiredExtensions(IEnumerable<Type> extensions, Action<Sequence
         ///   sequence.WithRequiredExtension(typeof(foo.bar.MyExtension), s => {
         ///     s.Run(typeof(MyPass));
         ///   });
+        /// </code>
         /// </summary>
         /// <param name="extension">The extension to request</param>
         /// <param name="action">An action that will be invoked with the extensions marked required</param>

Editor/API/Fluent/Sequence/Sequence.cs

@@ -1,5 +1,6 @@
 #region
 
+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using nadena.dev.ndmf.model;
 
@@ -18,19 +19,35 @@ namespace nadena.dev.ndmf.fluent
     /// <code>
     /// sequence.Run(typeof(MyPass))      // returns DeclaringPass
     ///   .BeforePass(typeof(OtherPass)); // valid only on DeclaringPass
+    ///   .Then.Run(typeof(OtherPass));
     /// </code>
     /// </summary>
     public sealed class DeclaringPass
     {
         private readonly SolverContext _solverContext;
         private readonly BuildPhase _phase;
         private readonly SolverPass _pass;
+        private readonly Sequence _seq;
 
-        internal DeclaringPass(SolverPass pass, SolverContext solverContext, BuildPhase phase)
+        /// <summary>
+        /// Returns the original sequence that returned this DeclaringPass. This is useful for chaining multiple
+        /// pass declarations, like so:
+        ///
+        /// <code>
+        /// InPhase(Generating)
+        ///   .Run(typeof(PassOne))
+        ///   .Then.Run(typeof(PassTwo));
+        /// </code>
+        /// </summary>
+        [SuppressMessage("ReSharper", "ConvertToAutoProperty")]
+        public Sequence Then => _seq;
+
+        internal DeclaringPass(SolverPass pass, SolverContext solverContext, BuildPhase phase, Sequence seq)
         {
             _pass = pass;
             _solverContext = solverContext;
             _phase = phase;
+            _seq = seq;
         }
 
         /// <summary>
@@ -208,7 +225,7 @@ private DeclaringPass InternalRun(IPass pass, string sourceFile, int sourceLine)
             _priorPass = solverPass;
             OnNewPass(solverPass);
 
-            return new DeclaringPass(solverPass, _solverContext, _phase);
+            return new DeclaringPass(solverPass, _solverContext, _phase, this);
         }
 
         /// <summary>

Editor/API/IExtensionContext.cs

@@ -1,8 +1,20 @@
 namespace nadena.dev.ndmf
 {
+    /// <summary>
+    /// The IExtensionContext is declared by custom extension contexts.
+    /// </summary>
     public interface IExtensionContext
     {
+        /// <summary>
+        /// Invoked when the extension is activated.
+        /// </summary>
+        /// <param name="context"></param>
         void OnActivate(BuildContext context);
+
+        /// <summary>
+        /// Invoked when the extension is deactivated.
+        /// </summary>
+        /// <param name="context"></param>
         void OnDeactivate(BuildContext context);
     }
 }

Editor/API/Util/VisitAssets.cs

@@ -8,10 +8,22 @@
 
 namespace nadena.dev.ndmf.util
 {
+    /// <summary>
+    /// This class provides helpers to traverse assets or asset properties referenced from a given root object.
+    /// </summary>
     public static class VisitAssets
     {
         public delegate bool AssetFilter(Object obj);
 
+        /// <summary>
+        /// Returns an enumerable of all assets referenced by the given root object.
+        /// </summary>
+        /// <param name="root">The asset to start traversal from</param>
+        /// <param name="traverseSaved">If false, traversal will not return assets that are saved</param>
+        /// <param name="includeScene">If false, scene assets will not be returned</param>
+        /// <param name="traversalFilter">If provided, this filter will be queried for each object encountered; if it
+        /// returns false, the selected object and all objects referenced from it will be ignored.</param>
+        /// <returns>An enumerable of objects found</returns>
         public static IEnumerable<Object> ReferencedAssets(
             this Object root,
             bool traverseSaved = true,
@@ -101,8 +113,18 @@ public static IEnumerable<Object> ReferencedAssets(
         }
     }
 
+    /// <summary>
+    /// Provides helpers to walk the properties of a SerializedObject
+    /// </summary>
     public static class WalkObjectProps
     {
+        /// <summary>
+        /// Returns an enumerable that will return _most_ of the properties of a SerializedObject. In particular, this
+        /// skips the contents of certain large arrays (e.g. the character contents of strings and the contents of
+        /// AnimationClip curves).
+        /// </summary>
+        /// <param name="obj">The SerializedObject to traverse</param>
+        /// <returns>The SerializedProperties found</returns>
         public static IEnumerable<SerializedProperty> AllProperties(this SerializedObject obj)
         {
             var target = obj.targetObject;
@@ -144,6 +166,11 @@ public static IEnumerable<SerializedProperty> AllProperties(this SerializedObjec
             }
         }
 
+        /// <summary>
+        /// Returns all ObjectReference properties of a SerializedObject
+        /// </summary>
+        /// <param name="obj"></param>
+        /// <returns></returns>
         public static IEnumerable<SerializedProperty> ObjectProperties(this SerializedObject obj)
         {
             foreach (var prop in obj.AllProperties())

Editor/ApplyOnPlay.cs

@@ -26,6 +26,7 @@
 
 #region
 
+using nadena.dev.ndmf.config;
 using nadena.dev.ndmf.runtime;
 using UnityEditor;
 using UnityEngine;
@@ -60,7 +61,7 @@ static ApplyOnPlay()
         private static void MaybeProcessAvatar(ApplyOnPlayGlobalActivator.OnDemandSource source,
             MonoBehaviour component)
         {
-            if (Settings.ApplyOnPlay && source == armedSource && component != null)
+            if (Config.ApplyOnPlay && source == armedSource && component != null)
             {
                 var avatar = RuntimeUtil.FindAvatarInParents(component.transform);
                 if (avatar == null) return;

Editor/AvatarProcessor.cs

@@ -113,7 +113,7 @@ public static void ProcessAvatar(GameObject root)
             ProcessAvatar(buildContext, BuildPhase.Resolving, BuildPhase.Optimizing);
             buildContext.Finish();
 
-            if (RuntimeUtil.isPlaying)
+            if (RuntimeUtil.IsPlaying)
             {
                 root.AddComponent<AlreadyProcessedTag>();
             }

Editor/Settings.cs → Editor/Config.cs

@@ -29,12 +29,16 @@
 
 #endregion
 
-namespace nadena.dev.ndmf
+namespace nadena.dev.ndmf.config
 {
-    public static class Settings
+    public static class Config
     {
+        // Preserve apply-on-play config from pre-1.8 versions of Modular Avatar
         private const string PREFKEY_APPLY_ON_PLAY = "nadena.dev.modular-avatar.applyOnPlay";
 
+        /// <summary>
+        /// Controls whether NDMF transformations will be applied at play time.
+        /// </summary>
         public static bool ApplyOnPlay
         {
             get => EditorPrefs.GetBool(PREFKEY_APPLY_ON_PLAY, true);
@@ -45,7 +49,11 @@ public static bool ApplyOnPlay
             }
         }
 
+        /// <summary>
+        /// This event will be invoked when any config value changes.
+        /// </summary>
         public static event Action OnChange;
+
         private static void NotifyChange() => OnChange?.Invoke();
     }
 }

Editor/GlobalInit.cs

@@ -12,7 +12,7 @@ internal static class GlobalInit
     {
         static GlobalInit()
         {
-            RuntimeUtil.delayCall = call => { EditorApplication.delayCall += () => call(); };
+            RuntimeUtil.DelayCall = call => { EditorApplication.delayCall += () => call(); };
         }
     }
 }

Editor/UI/Menus.cs

@@ -1,5 +1,6 @@
 #region
 
+using nadena.dev.ndmf.config;
 using UnityEditor;
 using UnityObject = UnityEngine.Object;
 
@@ -16,7 +17,7 @@ internal static class Menus
         static void Init()
         {
             EditorApplication.delayCall += OnSettingsChanged;
-            Settings.OnChange += OnSettingsChanged;
+            Config.OnChange += OnSettingsChanged;
         }
 
         // Avoid cluttering the GameObject context menu with duplicate entries. Users are more familiar with MA anyway,
@@ -38,12 +39,12 @@ public static void ApplyToCurrentAvatarGameobject()
         [MenuItem(APPLY_ON_PLAY_MENU_NAME, false, APPLY_ON_PLAY_PRIO)]
         private static void ApplyOnPlay()
         {
-            Settings.ApplyOnPlay = !Settings.ApplyOnPlay;
+            Config.ApplyOnPlay = !Config.ApplyOnPlay;
         }
 
         private static void OnSettingsChanged()
         {
-            Menu.SetChecked(APPLY_ON_PLAY_MENU_NAME, Settings.ApplyOnPlay);
+            Menu.SetChecked(APPLY_ON_PLAY_MENU_NAME, Config.ApplyOnPlay);
         }
     }
 }

Runtime/ApplyOnPlayGlobalActivator.cs

@@ -48,7 +48,7 @@ internal enum OnDemandSource
 
         private void Awake()
         {
-            if (!RuntimeUtil.isPlaying || this == null) return;
+            if (!RuntimeUtil.IsPlaying || this == null) return;
 
             var scene = gameObject.scene;
             foreach (var root in scene.GetRootGameObjects())
@@ -117,13 +117,13 @@ public class AvatarActivator : MonoBehaviour
     {
         private void Awake()
         {
-            if (!RuntimeUtil.isPlaying || this == null) return;
+            if (!RuntimeUtil.IsPlaying || this == null) return;
             ApplyOnPlayGlobalActivator.OnDemandProcessAvatar(ApplyOnPlayGlobalActivator.OnDemandSource.Awake, this);
         }
 
         private void Start()
         {
-            if (!RuntimeUtil.isPlaying || this == null) return;
+            if (!RuntimeUtil.IsPlaying || this == null) return;
             ApplyOnPlayGlobalActivator.OnDemandProcessAvatar(ApplyOnPlayGlobalActivator.OnDemandSource.Start, this);
         }
 

Runtime/GeneratedAssets.cs

@@ -4,6 +4,9 @@
 
 namespace nadena.dev.ndmf.runtime
 {
+    /// <summary>
+    /// This ScriptableObject is used as the root asset when storing generated assets.
+    /// </summary>
     [PreferBinarySerialization]
     public class GeneratedAssets : ScriptableObject
     {

Runtime/RuntimeUtil.cs

@@ -15,11 +15,11 @@ public static class RuntimeUtil
         /// Invoke this function to register a callback with EditorApplication.delayCall from a context that cannot
         /// access EditorApplication.
         /// </summary>
-        public static Action<Action> delayCall { get; internal set; }
+        public static Action<Action> DelayCall { get; internal set; }
 
         static RuntimeUtil()
         {
-            delayCall = action => { throw new Exception("delayCall() cannot be called during static initialization"); };
+            DelayCall = action => { throw new Exception("delayCall() cannot be called during static initialization"); };
         }
 
         // Shadow the VRC-provided methods to avoid deprecation warnings
@@ -39,9 +39,9 @@ internal static T GetOrAddComponent<T>(this Component obj) where T : Component
         /// Returns whether the editor is in play mode.
         /// </summary>
 #if UNITY_EDITOR
-        public static bool isPlaying => UnityEditor.EditorApplication.isPlayingOrWillChangePlaymode;
+        public static bool IsPlaying => UnityEditor.EditorApplication.isPlayingOrWillChangePlaymode;
 #else
-        public static bool isPlaying => true;
+        public static bool IsPlaying => true;
 #endif
 
         /// <summary>

docfx~/api/index.md

@@ -1,2 +1,3 @@
-# PLACEHOLDER
-TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*!
+# API Documentation
+
+Click the namespace entries on the left to see detailed API documentation.