From 0d3538c932affa45316c8c7caef86f8fddcf06a9 Mon Sep 17 00:00:00 2001
From: Antony Male <antony.male@gmail.com>
Date: Thu, 10 Apr 2014 13:11:47 +0100
Subject: [PATCH] Document ViewManager a bit

---
 .../CustomViewManager.cs                      |  2 +-
 Stylet/ViewManager.cs                         | 23 ++++++++++++++++---
 Stylet/WindowManager.cs                       |  2 +-
 StyletUnitTests/WindowManagerTests.cs         |  4 ++--
 4 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/Samples/Stylet.Samples.OverridingViewManager/CustomViewManager.cs b/Samples/Stylet.Samples.OverridingViewManager/CustomViewManager.cs
index 4b4b7f0..aee9912 100644
--- a/Samples/Stylet.Samples.OverridingViewManager/CustomViewManager.cs
+++ b/Samples/Stylet.Samples.OverridingViewManager/CustomViewManager.cs
@@ -38,7 +38,7 @@ namespace Stylet.Samples.OverridingViewManager
             this.viewModelToViewMapping = mappings.ToDictionary(x => x.ViewModel, x => x.View);
         }
 
-        public override UIElement LocateViewForModel(object model)
+        public override UIElement CreateViewForModel(object model)
         {
             Type viewType;
             if (!this.viewModelToViewMapping.TryGetValue(model.GetType(), out viewType))
diff --git a/Stylet/ViewManager.cs b/Stylet/ViewManager.cs
index eb015c3..a0c5a50 100644
--- a/Stylet/ViewManager.cs
+++ b/Stylet/ViewManager.cs
@@ -10,10 +10,27 @@ using System.Windows;
 
 namespace Stylet
 {
+    /// <summary>
+    /// Responsible for managing views. Locates the correct view, instantiates it, attaches it to its ViewModel correctly, and handles the View.Model attached property
+    /// </summary>
     public interface IViewManager
     {
+        /// <summary>
+        /// Called by the View.Model attached property when the ViewModel its bound to changes
         void OnModelChanged(DependencyObject targetLocation, DependencyPropertyChangedEventArgs e);
-        UIElement LocateViewForModel(object model);
+
+        /// <summary>
+        /// Given an instance of a ViewModel, locate the correct view for it, and instantiate it
+        /// </summary>
+        /// <param name="model">ViewModel to locate the view for</param>
+        /// <returns>An instance of the correct view</returns>
+        UIElement CreateViewForModel(object model);
+
+        /// <summary>
+        /// Given an instance of a ViewModel and an instance of its View, bind the two together
+        /// </summary>
+        /// <param name="view">View to bind to the ViewModel</param>
+        /// <param name="viewModel">ViewModel to bind the View to</param>
         void BindViewToModel(UIElement view, object viewModel);
     }
 
@@ -34,7 +51,7 @@ namespace Stylet
                 }
                 else
                 {
-                    view = this.LocateViewForModel(e.NewValue);
+                    view = this.CreateViewForModel(e.NewValue);
                     this.BindViewToModel(view, e.NewValue);
                 }
 
@@ -46,7 +63,7 @@ namespace Stylet
             }
         }
 
-        public virtual UIElement LocateViewForModel(object model)
+        public virtual UIElement CreateViewForModel(object model)
         {
             var modelName = model.GetType().FullName;
             var viewName = Regex.Replace(modelName, @"ViewModel", "View");
diff --git a/Stylet/WindowManager.cs b/Stylet/WindowManager.cs
index c77f363..f7647cc 100644
--- a/Stylet/WindowManager.cs
+++ b/Stylet/WindowManager.cs
@@ -32,7 +32,7 @@ namespace Stylet
         {
             var viewManager = IoC.Get<IViewManager>();
 
-            var view = viewManager.LocateViewForModel(viewModel);
+            var view = viewManager.CreateViewForModel(viewModel);
             var window = view as Window;
             if (window == null)
                 throw new Exception(String.Format("Tried to show {0} as a window, but it isn't a Window", view == null ? "(null)" : view.GetType().Name));
diff --git a/StyletUnitTests/WindowManagerTests.cs b/StyletUnitTests/WindowManagerTests.cs
index 24e107f..1acf8d6 100644
--- a/StyletUnitTests/WindowManagerTests.cs
+++ b/StyletUnitTests/WindowManagerTests.cs
@@ -29,7 +29,7 @@ namespace StyletUnitTests
         public void ShowWindowAsksViewManagerForView()
         {
             var model = new object();
-            this.viewManager.Setup(x => x.LocateViewForModel(model)).Verifiable();
+            this.viewManager.Setup(x => x.CreateViewForModel(model)).Verifiable();
             // Don't care if this throws - that's OK
             try { this.windowManager.ShowWindow(model);  }
             catch (Exception) { }
@@ -40,7 +40,7 @@ namespace StyletUnitTests
         public void ShowWindowThrowsIfViewIsntAWindow()
         {
             var model = new object();
-            this.viewManager.Setup(x => x.LocateViewForModel(model)).Returns(new UIElement());
+            this.viewManager.Setup(x => x.CreateViewForModel(model)).Returns(new UIElement());
             Assert.Throws<Exception>(() => this.windowManager.ShowWindow(model));
         }
     }