Merge pull request #127 from JakeGinnivan/XmlCommentsUpdate

Xml comments update

Author: Jake Ginnivan

src/TestStack.White.UnitTests/UIItems/DateFormatTest.cs

@@ -8,8 +8,8 @@ public class DateFormatTest
         [Fact]
         public void DifferentDateFormats()
         {
-            Assert.Equal(DateFormat.dayMonthYear, DateFormat.Create("-", "dd-MM-yyyy"));
-            Assert.Equal(DateFormat.dayMonthYear, DateFormat.Create("-", "d-M-yyyy"));
+            Assert.Equal(DateFormat.DayMonthYear, DateFormat.Create("-", "dd-MM-yyyy"));
+            Assert.Equal(DateFormat.DayMonthYear, DateFormat.Create("-", "d-M-yyyy"));
         }
     }
 }

src/TestStack.White/Application.cs

@@ -38,8 +38,9 @@ private Application(Process process)
         /// <summary>
         /// Runs the process identified by the executable and creates Application object for this executable
         /// </summary>
-        /// <param name="executable">location of the executable</param>
-        /// <returns></returns>
+        /// <param name="executable">Path to the executable</param>
+        /// <exception cref="ArgumentNullException">No process info passed</exception>
+        /// <exception cref="WhiteException">White Failed to Launch or Attached to process</exception>
         public static Application Launch(string executable)
         {
             var processStartInfo = new ProcessStartInfo(executable);
@@ -49,8 +50,8 @@ public static Application Launch(string executable)
         /// <summary>
         /// Lauches the process and creates and Application object for it
         /// </summary>
-        /// <param name="processStartInfo"></param>
-        /// <returns></returns>
+        /// <exception cref="ArgumentNullException">No process info passed</exception>
+        /// <exception cref="WhiteException">White Failed to Launch or Attached to process</exception>
         public static Application Launch(ProcessStartInfo processStartInfo)
         {
             if (string.IsNullOrEmpty(processStartInfo.WorkingDirectory)) processStartInfo.WorkingDirectory = ".";
@@ -89,22 +90,27 @@ public static Application Launch(ProcessStartInfo processStartInfo)
         }
 
         /// <summary>
-        /// Creates an Application object for existing process 
+        /// Attaches White to an existing process by process id 
         /// </summary>
-        /// <param name="processId"></param>
-        /// <returns></returns>
+        /// <exception cref="WhiteException">White Failed to Attach to process</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;
+            try
+            {
+                process = Process.GetProcessById(processId);
+            }
+            catch (ArgumentException e)
+            {
+                throw new WhiteException("Could not find process with id: " + processId, e);
+            }
             return new Application(process);
         }
 
         /// <summary>
-        /// Attaches with existing process
+        /// Attaches White to an existing process
         /// </summary>
-        /// <param name="process"></param>
-        /// <returns></returns>
+        /// <exception cref="WhiteException">White Failed to Attach to process</exception>
         public static Application Attach(Process process)
         {
             return new Application(process);
@@ -113,8 +119,7 @@ public static Application Attach(Process process)
         /// <summary>
         /// Attaches with existing process
         /// </summary>
-        /// <param name="executable"></param>
-        /// <returns></returns>
+        /// <exception cref="WhiteException">White Failed to Attach to process with specified name</exception>
         public static Application Attach(string executable)
         {
             Process[] processes = Process.GetProcessesByName(executable);
@@ -127,6 +132,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">White Failed to Launch or Attach to process</exception>
         public static Application AttachOrLaunch(ProcessStartInfo processStartInfo)
         {
             string processName = ReplaceLast(processStartInfo.FileName, ".exe", string.Empty);
@@ -165,17 +173,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">The application type is not supported by White</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">The application type is not supported by White</exception>
         public virtual Window GetWindow(string title)
         {
             return GetWindow(title, InitializeOption.NoCache);
@@ -187,6 +197,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">The application type is not supported by White</exception>
         public virtual Window GetWindow(SearchCriteria searchCriteria, InitializeOption initializeOption)
         {
             WindowSession windowSession = applicationSession.WindowSession(initializeOption);
@@ -234,6 +245,7 @@ public virtual void Kill()
         /// All windows belonging to the application
         /// </summary>
         /// <returns></returns>
+        /// <exception cref="UIItemSearchException">The application type is not supported by White</exception>
         public virtual List<Window> GetWindows()
         {
             return windowFactory.DesktopWindows(process, new NoApplicationSession());
@@ -289,6 +301,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">The application type is not supported by White</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">The application type is not supported by White</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">The application type is not supported by White</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">The application type is not supported by White</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">The application type is not supported by White</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">The application type is not supported by White</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">The application type is not supported by White</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">The application type is not supported by White</exception>
         public virtual List<Window> DesktopWindows()
         {
             var windows = new List<Window>();

src/TestStack.White/UIItems/DateFormat.cs

@@ -10,12 +10,12 @@ namespace TestStack.White.UIItems
     /// </summary>
     public class DateFormat
     {
-        public static DateFormat dayMonthYear = new DateFormat(DateUnit.Day, DateUnit.Month, DateUnit.Year);
-        public static DateFormat dayYearMonth = new DateFormat(DateUnit.Day, DateUnit.Year, DateUnit.Month);
-        public static DateFormat monthDayYear = new DateFormat(DateUnit.Month, DateUnit.Day, DateUnit.Year);
-        public static DateFormat monthYearDay = new DateFormat(DateUnit.Month, DateUnit.Year, DateUnit.Day);
-        public static DateFormat yearMonthDay = new DateFormat(DateUnit.Year, DateUnit.Month, DateUnit.Day);
-        public static DateFormat yearDayMonth = new DateFormat(DateUnit.Year, DateUnit.Day, DateUnit.Month);
+        public static DateFormat DayMonthYear = new DateFormat(DateUnit.Day, DateUnit.Month, DateUnit.Year);
+        public static DateFormat DayYearMonth = new DateFormat(DateUnit.Day, DateUnit.Year, DateUnit.Month);
+        public static DateFormat MonthDayYear = new DateFormat(DateUnit.Month, DateUnit.Day, DateUnit.Year);
+        public static DateFormat MonthYearDay = new DateFormat(DateUnit.Month, DateUnit.Year, DateUnit.Day);
+        public static DateFormat YearMonthDay = new DateFormat(DateUnit.Year, DateUnit.Month, DateUnit.Day);
+        public static DateFormat YearDayMonth = new DateFormat(DateUnit.Year, DateUnit.Day, DateUnit.Month);
 
         private readonly List<DateUnit> dateUnits = new List<DateUnit>();
 
@@ -49,6 +49,9 @@ public static DateFormat Create(string dateSeparator, string pattern)
             return dateFormat;
         }
 
+        /// <summary>
+        /// Use ',' as separator.
+        /// </summary>
         public static DateFormat Parse(string @string)
         {
             string[] parts = @string.Split(',');

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
         {