Update documentation

Author: Odotocodot

Odotocodot.OneNote.Linq/IOneNoteItemExtensions.cs

@@ -4,43 +4,66 @@
 
 namespace Odotocodot.OneNote.Linq
 {
+    /// <summary>
+    /// A static class containing extension methods for the <see cref="IOneNoteItem"/> object.
+    /// </summary>
     public static class IOneNoteItemExtensions
     {
-        //Depth first traversal 
-        public static IEnumerable<IOneNoteItem> Traverse(this IOneNoteItem item, Func<IOneNoteItem, bool> predicate)
+        /// <summary>
+        /// Returns a flattened collection of OneNote items, that contains the children of every OneNote item from the <paramref name="source"/>.
+        /// </summary>
+        /// <param name="source">The source OneNote item.</param>
+        /// <returns>An <see cref="IEnumerable{T}">IEnumerable</see>&lt;<see cref="IOneNoteItem"/>&gt; containing the 
+        /// child items of the <paramref name="source"/>.</returns>
+        /// <remarks>This method uses a non recursive depth first traversal algorithm.</remarks>
+        public static IEnumerable<IOneNoteItem> Traverse(this IOneNoteItem source)
         {
             var stack = new Stack<IOneNoteItem>();
-            stack.Push(item);
+            stack.Push(source);
             while (stack.Count > 0)
             {
                 var current = stack.Pop();
 
-                if (predicate(current))
-                    yield return current;
+                yield return current;
 
                 foreach (var child in current.Children)
                     stack.Push(child);
             }
         }
-        public static IEnumerable<IOneNoteItem> Traverse(this IOneNoteItem item)
+
+        /// <summary>
+        /// Returns a filtered flattened collection of OneNote items, that contains the children of every OneNote item 
+        /// from the <paramref name="source"/>.<br/>
+        /// Only items that successfully pass the <paramref name="predicate"/> are returned.
+        /// </summary>
+        /// <param name="source"><inheritdoc cref="Traverse(IOneNoteItem)" path="/param[@name='source']"/></param>
+        /// <param name="predicate">A function to test each item for a condition.</param>
+        /// <returns>An <see cref="IEnumerable{T}">IEnumerable</see>&lt;<see cref="IOneNoteItem"/>&gt; containing the 
+        /// child items of the <paramref name="source"/> that pass the <paramref name="predicate"/>.</returns>
+        /// <remarks><inheritdoc cref="Traverse(IOneNoteItem)" path="/remarks"/></remarks>
+        public static IEnumerable<IOneNoteItem> Traverse(this IOneNoteItem source, Func<IOneNoteItem, bool> predicate)
         {
             var stack = new Stack<IOneNoteItem>();
-            stack.Push(item);
+            stack.Push(source);
             while (stack.Count > 0)
             {
                 var current = stack.Pop();
 
-                yield return current;
+                if (predicate(current))
+                    yield return current;
 
                 foreach (var child in current.Children)
                     stack.Push(child);
             }
         }
 
-        public static IEnumerable<IOneNoteItem> Traverse(this IEnumerable<IOneNoteItem> items, Func<IOneNoteItem, bool> predicate) 
-            => items.SelectMany(item => item.Traverse(predicate));
-        public static IEnumerable<IOneNoteItem> Traverse(this IEnumerable<IOneNoteItem> items) 
-            => items.SelectMany(item => item.Traverse());
+        /// <inheritdoc cref="Traverse(IOneNoteItem)"/>
+        public static IEnumerable<IOneNoteItem> Traverse(this IEnumerable<IOneNoteItem> source)
+            => source.SelectMany(item => item.Traverse());
+
+        /// <inheritdoc cref="Traverse(IOneNoteItem,Func{IOneNoteItem, bool})"/>
+        public static IEnumerable<IOneNoteItem> Traverse(this IEnumerable<IOneNoteItem> source, Func<IOneNoteItem, bool> predicate)
+            => source.SelectMany(item => item.Traverse(predicate));
 
         /// <inheritdoc cref="OneNoteParser.OpenInOneNote(Microsoft.Office.Interop.OneNote.IApplication, IOneNoteItem)"/>
         public static void OpenInOneNote(this IOneNoteItem item) => OneNoteApplication.OpenInOneNote(item);
@@ -51,11 +74,18 @@ public static IEnumerable<IOneNoteItem> Traverse(this IEnumerable<IOneNoteItem>
         /// <inheritdoc cref="OneNoteParser.GetPageContent(Microsoft.Office.Interop.OneNote.IApplication, OneNotePage)"/>
         public static string GetPageContent(this OneNotePage page) => OneNoteApplication.GetPageContent(page);
 
-        ///// <summary>
-        ///// Returns
-        ///// </summary>
-        ///// <param name="item"></param>
-        ///// <returns> <see langword="true"/> if the item is a deleted page <see cref="OneNotePage.IsInRecycleBin"/>, deleted section, recycle bin section group, or deleted pages section.</returns>
+        /// <summary>
+        /// Returns a value that indicates whether the <paramref name="item"/> is in or is a recycle bin.
+        /// </summary>
+        /// <param name="item">The OneNote item to check.</param>
+        /// <returns><see langword="true"/> if the <paramref name="item"/> is in or is a recycle bin; otherwise, <see langword="false"/>.</returns>
+        /// <remarks>Checks whether the <paramref name="item"/> is a recycle bin <see cref="OneNoteSectionGroup">section group</see>,
+        /// a deleted <see cref="OneNotePage">page</see>, a deleted <see cref="OneNoteSection">section</see>, or the deleted pages 
+        /// <see cref="OneNoteSection">section</see> within a recycle bin.</remarks>
+        /// <seealso cref="OneNoteSectionGroup.IsRecycleBin"/>
+        /// <seealso cref="OneNoteSection.IsInRecycleBin"/>
+        /// <seealso cref="OneNoteSection.IsDeletedPages"/>
+        /// <seealso cref="OneNotePage.IsInRecycleBin"/>
         public static bool IsInRecycleBin(this IOneNoteItem item) => item switch
         {
             OneNoteSectionGroup sectionGroup => sectionGroup.IsRecycleBin,
@@ -64,22 +94,31 @@ public static IEnumerable<IOneNoteItem> Traverse(this IEnumerable<IOneNoteItem>
             _ => false,
         };
 
+        /// <summary>
+        /// Get the recycle bin <see cref="OneNoteSectionGroup">section group</see> for the specified <paramref name="notebook"/> if it exists.
+        /// </summary>
+        /// <param name="notebook">The notebook to get the recycle bin of.</param>
+        /// <param name="sectionGroup">When this method returns, <paramref name="sectionGroup"/> contains the recycle bin of 
+        /// the <paramref name="notebook"/> if it was found; 
+        /// otherwise, <see langword="null"/>.</param>
+        /// <returns><see langword="true"/> if the <paramref name="notebook"/> contains a recycle bin; otherwise, <see langword="false"/>.</returns>
         public static bool GetRecycleBin(this OneNoteNotebook notebook, out OneNoteSectionGroup sectionGroup)
         {
             sectionGroup = notebook.SectionGroups.FirstOrDefault(sg => sg.IsRecycleBin);
             return sectionGroup != null;
         }
 
+        /// <summary>
+        /// Returns a flattened collection of all the <see cref="OneNotePage">pages</see> present in the <paramref name="source"/>.
+        /// </summary>
+        /// <param name="source"><inheritdoc cref="Traverse(IOneNoteItem)" path="/param[@name='source']"/></param>
+        /// <returns>An <see cref="IEnumerable{T}">IEnumerable</see>&lt;<see cref="OneNotePage"/>&gt; containing all the 
+        /// <see cref="OneNotePage">pages</see> present in the <paramref name="source"/>.</returns>
+        public static IEnumerable<OneNotePage> GetPages(this IOneNoteItem source)
+            => (IEnumerable<OneNotePage>)source.Traverse(i => i is OneNotePage);
 
-        ///// <param name="items">The collection of items to filter get pages from.</param>
-        ///// <returns>
-        ///// A flattened collection of only the pages nested in <paramref name="items"/>.
-        ///// </returns>
-        public static IEnumerable<OneNotePage> GetPages(this IEnumerable<IOneNoteItem> items) => (IEnumerable<OneNotePage>)items.Traverse(i => i is OneNotePage);
-        ///// <param name="item">The item to filter get pages from.</param>
-        ///// <returns>
-        ///// A flattened collection of only the pages nested in <paramref name="item"/>.
-        ///// </returns>
-        public static IEnumerable<OneNotePage> GetPages(this IOneNoteItem item) => (IEnumerable<OneNotePage>)item.Traverse(i => i is OneNotePage);
+        /// <inheritdoc cref="GetPages(IOneNoteItem)"/>
+        public static IEnumerable<OneNotePage> GetPages(this IEnumerable<IOneNoteItem> source)
+            => (IEnumerable<OneNotePage>)source.Traverse(i => i is OneNotePage);
     }
 }

Odotocodot.OneNote.Linq/OneNoteApplication.cs

@@ -1,18 +1,37 @@
-using System;
-using System.Collections.Generic;
+using System.Collections.Generic;
 using System.Diagnostics;
 using System.Runtime.InteropServices;
 using System.Threading;
 using Microsoft.Office.Interop.OneNote;
 
 namespace Odotocodot.OneNote.Linq
 {
-    //wrapper around com object for easy release of com object
+    /// <summary>
+    /// A static wrapper class around the <see cref="Application"/> class, allowing for easy acquirement and
+    /// release of a OneNote COM object, whilst avoiding duplicate instances. In addition to exposing the 
+    /// <see href="https://learn.microsoft.com/en-us/office/client-developer/onenote/application-interface-onenote">OneNote's API</see>
+    /// </summary>
+    /// <remarks>A <see cref="Application">OneNote COM object</see> is required to access any of the OneNote API.</remarks>
     public static class OneNoteApplication
     {
         private static Application oneNote;
         private static bool hasComInstance = false;
+        /// <summary>
+        /// Indicates whether the class has a usable <see cref="Application">COM instance</see>.
+        /// </summary>
+        /// <remarks>When <see langword="true"/> a OneNote process should be visible in the Task Manager.</remarks>
+        /// <seealso cref="Init"/>
+        /// <seealso cref="ReleaseComInstance"/>
         public static bool HasComInstance => hasComInstance;
+
+        /// <summary>
+        /// Initialises the static class by acquiring a <see cref="Application">OneNote COM object</see>.
+        /// </summary>
+        /// <exception cref="COMException">Thrown if an error occurred when trying to get the 
+        /// <see cref="Application">OneNote COM object</see> or the number of attempts in doing 
+        /// so exceeded the limit.</exception>
+        /// <seealso cref="HasComInstance"/>
+        /// <seealso cref="ReleaseComInstance"/>
         public static void Init()
         {
             int attempt = 0;
@@ -60,17 +79,6 @@ public static string GetPageContent(OneNotePage page)
             return OneNoteParser.GetPageContent(oneNote, page);
         }
 
-        public static IEnumerable<IOneNoteItem> Traverse()
-        {
-            Init();
-            return GetNotebooks().Traverse();
-        }
-        public static IEnumerable<IOneNoteItem> Traverse(Func<IOneNoteItem, bool> predicate)
-        {
-            Init();
-            return GetNotebooks().Traverse(predicate);
-        }
-
         /// <inheritdoc cref="OneNoteParser.FindPages(IApplication, string)"/>
         public static IEnumerable<OneNotePage> FindPages(string search)
         {
@@ -136,6 +144,11 @@ public static void CreateNotebook(string notebookName)
             OneNoteParser.CreateNotebook(oneNote, notebookName, true);
         }
 
+        /// <summary>
+        /// Releases the <see cref="Application">OneNote COM object</see> freeing memory.
+        /// </summary>
+        /// <seealso cref="Init"/>
+        /// <seealso cref="HasComInstance"/>
         public static void ReleaseComInstance()
         {
             if (hasComInstance)