From 0b24ab0881964d0c43e650a9fabdf41b28f02448 Mon Sep 17 00:00:00 2001
From: Matteo Cominetti <matteo@cominetti.org>
Date: Tue, 30 Jun 2020 22:22:02 +0100
Subject: [PATCH] comments

---
 xUnitRevitUtils/xru.cs | 45 +++++++++++++++++++++++++++++++-----------
 1 file changed, 33 insertions(+), 12 deletions(-)

diff --git a/xUnitRevitUtils/xru.cs b/xUnitRevitUtils/xru.cs
index e8b0912..a539bc4 100644
--- a/xUnitRevitUtils/xru.cs
+++ b/xUnitRevitUtils/xru.cs
@@ -11,6 +11,9 @@ using Xunit;
 
 namespace xUnitRevitUtils
 {
+  /// <summary>
+  /// Utility class with methods and properties used by the xUnit Revit plugin
+  /// </summary>
   public static class xru
   {
     private static UIApplication Uiapp { get; set; }
@@ -20,9 +23,6 @@ namespace xUnitRevitUtils
 
     private static SynchronizationContext UiContext { get; set; }
 
-    public static Document ActiveDoc { get { return Uiapp.ActiveUIDocument.Document; } }
-    public static Selection CuerrentSelection { get { return Uiapp.ActiveUIDocument.Selection; } }
-
     public static void Initialize(UIApplication uiapp, SynchronizationContext uiContext, ExternalEvent eventHandler, List<Action> queue)
     {
       Uiapp = uiapp;
@@ -31,8 +31,17 @@ namespace xUnitRevitUtils
       Queue = queue;
     }
 
+    #region utility methods
+
+
+    /// <summary>
+    /// Returns the selected elements in the active document
+    /// </summary>
+    /// <returns></returns>
     public static List<Element> GetActiveSelection()
     {
+      Assert.NotNull(Uiapp);
+
       if (Uiapp.ActiveUIDocument != null)
         return Uiapp.ActiveUIDocument.Selection.GetElementIds().Select(x => Uiapp.ActiveUIDocument.Document.GetElement(x)).ToList();
       return new List<Element>();
@@ -40,13 +49,13 @@ namespace xUnitRevitUtils
     /// <summary>
     /// Opens and activates a document if not open already
     /// </summary>
-    /// <param name="path"></param>
-    public static Document OpenDoc(string path)
+    /// <param name="filePath">Path to the file to open</param>
+    public static Document OpenDoc(string filePath)
     {
       Assert.NotNull(Uiapp);
       Document doc = null;
       //OpenAndActivateDocument only works if run from the current context
-      UiContext.Send(x => { doc = Uiapp.OpenAndActivateDocument(path).Document; }, null);
+      UiContext.Send(x => { doc = Uiapp.OpenAndActivateDocument(filePath).Document; }, null);
       Assert.NotNull(doc);
       return doc;
     }
@@ -55,15 +64,18 @@ namespace xUnitRevitUtils
     /// <summary>
     /// Creates a new empty document
     /// </summary>
-    /// <param name="path"></param>
-    public static Document CreateNewDoc(string templatePath, string filePath)
+    /// <param name="templatePath">Path to the project template</param>
+    /// <param name="filePath">Path where to save the new doc</param>
+    /// <param name="overwrite">If true overwrites existing files with same name</param>
+    /// <returns></returns>
+    public static Document CreateNewDoc(string templatePath, string filePath, bool overwrite = true)
     {
       Assert.NotNull(Uiapp);
       Document doc = null;
 
       try
       {
-        if (File.Exists(filePath))
+        if (overwrite && File.Exists(filePath))
           File.Delete(filePath);
       }
       catch { }
@@ -71,6 +83,7 @@ namespace xUnitRevitUtils
       //OpenAndActivateDocument only works if run from the current context
       UiContext.Send(x =>
       {
+        //if already open, just use it
         if (!File.Exists(filePath))
         {
           doc = Uiapp.Application.NewProjectDocument(templatePath);
@@ -85,19 +98,26 @@ namespace xUnitRevitUtils
       return doc;
     }
 
-    public static Task RunInTransaction(Action action, Document doc)
+
+    /// <summary>
+    /// Runs an Action in a Revit transaction, uses TaskCompletionSource to communicate when done
+    /// </summary>
+    /// <param name="action">Action to run</param>
+    /// <param name="doc">Revit Document</param>
+    /// <param name="transactionName">Transaction Name</param>
+    /// <returns></returns>
+    public static Task RunInTransaction(Action action, Document doc, string transactionName = "transaction")
     {
       var tcs = new TaskCompletionSource<string>();
       Queue.Add(new Action(() =>
       {
         try
         {
-          using (Transaction transaction = new Transaction(doc, "test transaction"))
+          using (Transaction transaction = new Transaction(doc, transactionName))
           {
             transaction.Start();
             action.Invoke();
             transaction.Commit();
-
           }
         }
         catch (Exception e)
@@ -111,5 +131,6 @@ namespace xUnitRevitUtils
 
       return tcs.Task;
     }
+#endregion
   }
 }