Comments to many methods, mainly about exceptions.

Author: ritro

src/TestStack.White/Application.cs

@@ -40,6 +40,8 @@ private Application(Process process)
         /// </summary>
         /// <param name="executable">location of the executable</param>
         /// <returns></returns>
+        /// <exception cref="ArgumentNullException"></exception>
+        /// <exception cref="WhiteException">when some error occured</exception>
         public static Application Launch(string executable)
         {
             var processStartInfo = new ProcessStartInfo(executable);
@@ -51,6 +53,8 @@ public static Application Launch(string executable)
         /// </summary>
         /// <param name="processStartInfo"></param>
         /// <returns></returns>
+        /// <exception cref="ArgumentNullException"></exception>
+        /// <exception cref="WhiteException">when some error occured</exception>
         public static Application Launch(ProcessStartInfo processStartInfo)
         {
             if (string.IsNullOrEmpty(processStartInfo.WorkingDirectory)) processStartInfo.WorkingDirectory = ".";
@@ -93,10 +97,18 @@ public static Application Launch(ProcessStartInfo processStartInfo)
         /// </summary>
         /// <param name="processId"></param>
         /// <returns></returns>
+        /// <exception cref="WhiteException">when process not found</exception>
         public static Application Attach(int processId)
         {
-            Process process = Process.GetProcessById(processId);
-            if (process == null) throw new WhiteException("Could not find process with id: " + processId);
+            Process process = null;
+            try
+            {
+                process = Process.GetProcessById(processId);
+            }
+            catch (System.ArgumentException e)
+            {
+                throw new WhiteException("Could not find process with id: " + processId, e);
+            }
             return new Application(process);
         }
 
@@ -115,6 +127,7 @@ public static Application Attach(Process process)
         /// </summary>
         /// <param name="executable"></param>
         /// <returns></returns>
+        /// <exception cref="WhiteException">when process is not found</exception>
         public static Application Attach(string executable)
         {
             Process[] processes = Process.GetProcessesByName(executable);
@@ -127,6 +140,9 @@ public static Application Attach(string executable)
         /// </summary>
         /// <param name="processStartInfo"></param>
         /// <returns></returns>
+        /// <exception cref="ArgumentException"></exception>
+        /// <exception cref="ArgumentNullException"></exception>
+        /// <exception cref="WhiteException">when some error occured</exception>
         public static Application AttachOrLaunch(ProcessStartInfo processStartInfo)
         {
             string processName = ReplaceLast(processStartInfo.FileName, ".exe", string.Empty);
@@ -165,17 +181,19 @@ public virtual ApplicationSession ApplicationSession
         /// <param name="title">Title text of window displayed on desktop</param>
         /// <param name="option">Option which would be used to initialize the window.</param>
         /// <returns></returns>
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         public virtual Window GetWindow(string title, InitializeOption option)
         {
             WindowSession windowSession = applicationSession.WindowSession(option);
             return windowFactory.CreateWindow(title, process, option, windowSession);
         }
 
         /// <summary>
-        /// Get visible window
+        /// Get visible window. NoCache option is set by default
         /// </summary>
         /// <param name="title">Title text of window displayed on desktop</param>
         /// <returns></returns>
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         public virtual Window GetWindow(string title)
         {
             return GetWindow(title, InitializeOption.NoCache);
@@ -187,6 +205,7 @@ public virtual Window GetWindow(string title)
         /// <param name="searchCriteria"></param>
         /// <param name="initializeOption">found window would be initialized with this option</param>
         /// <returns></returns>
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         public virtual Window GetWindow(SearchCriteria searchCriteria, InitializeOption initializeOption)
         {
             WindowSession windowSession = applicationSession.WindowSession(initializeOption);
@@ -234,6 +253,7 @@ public virtual void Kill()
         /// All windows belonging to the application
         /// </summary>
         /// <returns></returns>
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         public virtual List<Window> GetWindows()
         {
             return windowFactory.DesktopWindows(process, new NoApplicationSession());
@@ -289,6 +309,7 @@ public virtual void WaitWhileBusy()
         /// </summary>
         /// <param name="match"></param>
         /// <param name="initializeOption">option for the window which matches the condition</param>
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         public virtual Window Find(Predicate<string> match, InitializeOption initializeOption)
         {
             WindowSession windowSession = applicationSession.WindowSession(initializeOption);

src/TestStack.White/Factory/ChildWindowFactory.cs

@@ -44,6 +44,7 @@ protected virtual AutomationElement WaitTillFound(Func<AutomationElement> find,
             return element;
         }
 
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         internal static Window Create(AutomationElement element, InitializeOption option, WindowSession windowSession)
         {
             SpecializedWindowFactory specializedWindowFactory = SpecializedWindowFactories.Find(factory => factory.DoesSpecializeInThis(element));

src/TestStack.White/Factory/WindowFactory.cs

@@ -68,27 +68,31 @@ public virtual Window SplashWindow(Process process)
             return new SplashWindow(element, InitializeOption.NoCache);
         }
 
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         public virtual Window CreateWindow(string title, Process process, InitializeOption option, WindowSession windowSession)
         {
             var message = string.Format("Couldn't find window with title {0} in process {1}{2}", title, process.Id, ", after waiting for 30 seconds");
             var element = WaitTillFound(() => Finder.FindWindow(title, process.Id), message);
             return Create(element, option, windowSession);
         }
 
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         public virtual Window CreateWindow(SearchCriteria searchCriteria, Process process, InitializeOption option, WindowSession windowSession)
         {
             var message = string.Format("Couldn't find window with SearchCriteria {0} in process {1}{2}", searchCriteria, process.Id, Constants.BusyMessage);
             var element = WaitTillFound(() => Finder.FindWindow(searchCriteria, process.Id), message);
             return Create(element, option, windowSession);
         }
 
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         public virtual Window FindWindow(Process process, Predicate<string> match, InitializeOption initializeOption, WindowSession windowSession)
         {
             string message = string.Format("Could not find window matching condition. ProcessName: {0}, ProcessId: {1}, MatchingConditionMethod: {2}, MatchingConditionTarget: {3}", process.ProcessName, process.Id, match.Method, match.Target);
             var foundElement = WaitTillFound(() => FindWindowElement(process, match), message);
             return Create(foundElement, initializeOption, windowSession);
         }
 
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         public virtual Window FindModalWindow(string title, Process process, InitializeOption option, AutomationElement parentWindowElement,
                                               WindowSession windowSession)
         {
@@ -98,6 +102,7 @@ public virtual Window FindModalWindow(string title, Process process, InitializeO
             return Create(modalWindowElement, option, windowSession);
         }
 
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         public virtual Window FindModalWindow(SearchCriteria searchCriteria, InitializeOption option, AutomationElement parentWindowElement, WindowSession windowSession)
         {
             var windowFinder = new AutomationElementFinder(parentWindowElement);
@@ -132,6 +137,7 @@ private AutomationElement FindWindowElement(Process process, Predicate<string> m
             });
         }
 
+        /// <exception cref="UIItemSearchException">if your framework is not supported</exception>
         public virtual List<Window> DesktopWindows()
         {
             var windows = new List<Window>();

src/TestStack.White/UIItems/IUIItem.cs

@@ -95,4 +95,13 @@ public interface IUIItem : ActionListener
 
         void Enter(string value);
     }
+
+    /// <summary>
+    /// Class which inherits this interface has a mapping to it's Automation type.
+    /// Used for search constraints.
+    /// </summary>
+    public interface IMappableUIItem
+    {
+        
+    }
 }

src/TestStack.White/UIItems/IUIItemContainer.cs

@@ -4,11 +4,58 @@ namespace TestStack.White.UIItems
 {
     public interface IUIItemContainer : IUIItem
     {
-        T Get<T>() where T : UIItem;
-        T Get<T>(string primaryIdentification) where T : UIItem;
-        T Get<T>(SearchCriteria searchCriteria) where T : UIItem;
         ToolTip ToolTip { get; }
         ToolTip GetToolTipOn(UIItem uiItem);
         IUIItem[] GetMultiple(SearchCriteria criteria);
+
+        /// <summary>
+        /// Finds UIItem which matches specified type. Useful for non managed applications where controls are not identified by AutomationId, like in 
+        /// Managed applications. In case of multiple items of this type the first one found would be returned which cannot be guaranteed to be the same 
+        /// across multiple invocations.
+        /// </summary>
+        /// <typeparam name="T">IUIItem type e.g. Button, TextBox</typeparam>
+        /// <returns>First item of supplied type</returns>
+        /// <exception cref="AutomationException">when item not found</exception>
+        /// <exception cref="WhiteException">when any errors occured during search</exception>
+        T Get<T>() where T : IUIItem;
+
+        /// <summary>
+        /// Finds UIItem which matches specified type and identification. 
+        /// In case of multiple items of this type the first one found would be returned which cannot be guaranteed to be the same across multiple 
+        /// invocations. For managed applications this is name given to controls in the application code.
+        /// For unmanaged applications this is text of the control or label next to it if it doesn't have well defined text.
+        /// <!--e.g. TextBox doesn't have any predefined text of its own as it can be changed at runtime by user, hence is identified by the label next to it.
+        /// If there is no label then Get<T> or Get<T>(SearchCriteria) method can be used.-->
+        /// </summary>
+        /// <typeparam name="T">IUIItem implementation</typeparam>
+        /// <param name="primaryIdentification">For managed application this is the name provided in application code and unmanaged application this is 
+        /// the text or label next to it based identification</param>
+        /// <returns>First item of supplied type and identification</returns>
+        /// <exception cref="AutomationException">when item not found</exception>
+        /// <exception cref="WhiteException">when any errors occured during search</exception>
+        T Get<T>(string primaryIdentification) where T : IUIItem;
+
+        /// <summary>
+        /// Finds UIItem which matches specified type and searchCriteria. Type supplied need not be supplied again in SearchCondition.
+        /// <!--e.g. in Get<Button>(SearchCriteria.ByAutomationId("OK").ByControlType(typeof(Button)).Indexed(1) the ByControlType(typeof(Button)) part 
+        /// is redundant. Look at documentation of SearchCriteria for details on it.-->
+        /// </summary>
+        /// <code>
+        /// </code>
+        /// <typeparam name="T"></typeparam>
+        /// <param name="searchCriteria">Criteria provided to search UIItem</param>
+        /// <returns>First items matching the type and criteria</returns>
+        /// <exception cref="AutomationException">when item not found</exception>
+        /// <exception cref="WhiteException">when any errors occured during search</exception>
+        T Get<T>(SearchCriteria searchCriteria) where T : IUIItem;
+
+        /// <summary>
+        /// Finds UIItem which matches specified type and searchCriteria using the default BusyTimeout. Look at documentation of SearchCriteria for details on it.
+        /// </summary>
+        /// <param name="searchCriteria">Criteria provided to search IUIItem</param>
+        /// <returns>First items matching the criteria</returns>
+        /// <exception cref="AutomationException">when item not found</exception>
+        /// <exception cref="WhiteException">when any errors occured during search</exception>
+        IUIItem Get(SearchCriteria searchCriteria);
     }
 }

src/TestStack.White/UIItems/ListViewCells.cs

@@ -16,6 +16,7 @@ public ListViewCells(List<AutomationElement> collection, ActionListener actionLi
             this.header = header;
         }
 
+        /// <exception cref="UIActionException">when header row is not defined</exception>
         public virtual ListViewCell this[string columnName]
         {
             get

src/TestStack.White/UIItems/SelectionItem.cs

@@ -19,6 +19,7 @@ public virtual bool IsSelected
             }
         }
 
+        /// <exception cref="UIActionException"></exception>
         public virtual void Select()
         {
             if (!Bounds.IsEmpty) Click();

src/TestStack.White/UIItems/TextBox.cs

@@ -14,7 +14,8 @@ public TextBox(AutomationElement automationElement, ActionListener actionListene
 
         /// <summary>
         /// Enters the text in the textbox. The text would be cleared first. This is not as good performing as the BulkText method. 
-        /// This does raise all keyboard events.
+        /// This does raise all keyboard events - that means that your string will consist of letters that match the letters
+        /// of your string but in current input language.
         /// </summary>
         public virtual string Text
         {
@@ -34,6 +35,7 @@ public virtual string Text
 
         /// <summary>
         /// Sets the text in the textbox. The text would be cleared first. This is a better performing than the Text method. This doesn't raise all keyboard events.
+        /// The string will be set exactly as it is in your code.
         /// </summary>
         public virtual string BulkText
         {

src/TestStack.White/UIItems/UIItemContainer.cs

@@ -45,53 +45,21 @@ public UIItemContainer(AutomationElement automationElement, ActionListener actio
         {
         }
 
-        /// <summary>
-        /// Finds UIItem which matches specified type. Useful for non managed applications where controls are not identified by AutomationId, like in 
-        /// Managed applications. In case of multiple items of this type the first one found would be returned which cannot be guaranteed to be the same 
-        /// across multiple invocations.
-        /// </summary>
-        /// <typeparam name="T">UIItem type e.g. Button, TextBox</typeparam>
-        /// <returns>First item of supplied type</returns>
-        public virtual T Get<T>() where T : UIItem
+        public virtual T Get<T>() where T : IUIItem
         {
             return Get<T>(SearchCriteria.All);
         }
 
-        /// <summary>
-        /// Finds UIItem which matches specified type and identification. 
-        /// In case of multiple items of this type the first one found would be returned which cannot be guaranteed to be the same across multiple 
-        /// invocations. For managed applications this is name given to controls in the application code.
-        /// For unmanaged applications this is text of the control or label next to it if it doesn't have well defined text.
-        /// e.g. TextBox doesn't have any predefined text of its own as it can be changed at runtime by user, hence is identified by the label next to it.
-        /// If there is no label then Get<T> or Get<T>(SearchCriteria) method can be used.
-        /// </summary>
-        /// <typeparam name="T">UIItem type</typeparam>
-        /// <param name="primaryIdentification">For managed application this is the name provided in application code and unmanaged application this is 
-        /// the text or label next to it based identification</param>
-        /// <returns>First item of supplied type and identification</returns>
-        public virtual T Get<T>(string primaryIdentification) where T : UIItem
+        public virtual T Get<T>(string primaryIdentification) where T : IUIItem
         {
             return Get<T>(SearchCriteria.ByAutomationId(primaryIdentification));
         }
 
-        /// <summary>
-        /// Finds UIItem which matches specified type and searchCriteria. Type supplied need not be supplied again in SearchCondition.
-        /// e.g. in Get<Button>(SearchCriteria.ByAutomationId("OK").ByControlType(typeof(Button)).Indexed(1) the ByControlType(typeof(Button)) part 
-        /// is redundant. Look at documentation of SearchCriteria for details on it.
-        /// </summary>
-        /// <typeparam name="T"></typeparam>
-        /// <param name="searchCriteria">Criteria provided to search UIItem</param>
-        /// <returns>First items matching the type and criteria</returns>
-        public virtual T Get<T>(SearchCriteria searchCriteria) where T : UIItem
+        public virtual T Get<T>(SearchCriteria searchCriteria) where T : IUIItem
         {
             return (T) Get(searchCriteria.AndControlType(typeof (T), Framework));
         }
 
-        /// <summary>
-        /// Finds UIItem which matches specified type and searchCriteria using the default BusyTimeout. Look at documentation of SearchCriteria for details on it.
-        /// </summary>
-        /// <param name="searchCriteria">Criteria provided to search UIItem</param>
-        /// <returns>First items matching the criteria</returns>
         public virtual IUIItem Get(SearchCriteria searchCriteria)
         {
             return Get(searchCriteria, CoreAppXmlConfiguration.Instance.BusyTimeout());
@@ -100,9 +68,11 @@ public virtual IUIItem Get(SearchCriteria searchCriteria)
         /// <summary>
         /// Finds UIItem which matches specified type and searchCriteria. Look at documentation of SearchCriteria for details on it.
         /// </summary>
-        /// <param name="searchCriteria">Criteria provided to search UIItem</param>
+        /// <param name="searchCriteria">Criteria provided to search IUIItem</param>
         /// <param name="timeout">Time to wait for item to come on-screen before returning off-screen element, if found.</param>
         /// <returns>First items matching the criteria</returns>
+        /// <exception cref="AutomationException">when item not found</exception>
+        /// <exception cref="WhiteException">when any errors occured during search</exception>
         public virtual IUIItem Get(SearchCriteria searchCriteria, TimeSpan timeout)
         {
             try