From e2cfbb7accaa8f2b2f56779339251a666d295c4a Mon Sep 17 00:00:00 2001
From: Adam Fowler <adamfowler71@gmail.com>
Date: Mon, 15 Mar 2021 14:27:32 +0000
Subject: [PATCH] Make runMethod calls public, add some comments

---
 Sources/HummingbirdMustache/Context.swift     | 16 ++++--
 Sources/HummingbirdMustache/Method.swift      | 55 ++++++++++++++++---
 .../MethodTests.swift                         |  2 +-
 3 files changed, 61 insertions(+), 12 deletions(-)

diff --git a/Sources/HummingbirdMustache/Context.swift b/Sources/HummingbirdMustache/Context.swift
index 9b758ae..599accd 100644
--- a/Sources/HummingbirdMustache/Context.swift
+++ b/Sources/HummingbirdMustache/Context.swift
@@ -1,4 +1,5 @@
 
+/// Context that current object is being rendered in. Only really relevant when rendering a sequence
 struct HBMustacheContext: HBMustacheMethods {
     var first: Bool
     var last: Bool
@@ -10,6 +11,17 @@ struct HBMustacheContext: HBMustacheMethods {
         self.index = 0
     }
 
+    /// Apply method to `HBMustacheContext`. These are available when processing elements
+    /// of a sequence.
+    ///
+    /// Format your mustache as follows to accept them. They look like a function without any arguments
+    /// ```
+    /// {{#sequence}}{{index()}}{{/sequence}}
+    /// ```
+    ///
+    /// Methods available are `first`, `last`, and `index`
+    /// - Parameter name: Method name
+    /// - Returns: Result
     func runMethod(_ name: String) -> Any? {
         switch name {
         case "first":
@@ -18,10 +30,6 @@ struct HBMustacheContext: HBMustacheMethods {
             return self.last
         case "index":
             return self.index
-        case "even":
-            return (self.index & 1) == 0
-        case "odd":
-            return (self.index & 1) == 1
         default:
             return nil
         }
diff --git a/Sources/HummingbirdMustache/Method.swift b/Sources/HummingbirdMustache/Method.swift
index 6f30375..dcc2dd7 100644
--- a/Sources/HummingbirdMustache/Method.swift
+++ b/Sources/HummingbirdMustache/Method.swift
@@ -1,10 +1,29 @@
-
-protocol HBMustacheMethods {
+/// Objects that can have a methods run on them. Mustache methods are specific to this implementation
+/// of Mustache. They allow you to process objects before they are rendered.
+///
+/// The syntax for applying methods is `{{method(variable)}}`. Methods can be applied to both
+/// variables and sections.
+///
+/// A simple example would be ensuring a string is lowercase.
+/// ```
+/// {{lowercased(myString)}}
+/// ```
+/// If applying a method to a sequence then the closing element of the sequence should not include the
+/// method name eg
+/// ```
+/// {{#reversed(sequence)}}{{.}}{{\sequence}}
+/// ```
+public protocol HBMustacheMethods {
     func runMethod(_ name: String) -> Any?
 }
 
 extension StringProtocol {
-    func runMethod(_ name: String) -> Any? {
+    /// Apply method to String/Substring
+    ///
+    /// Methods available are `capitalized`, `lowercased`, `uppercased` and `reversed`
+    /// - Parameter name: Method name
+    /// - Returns: Result
+    public func runMethod(_ name: String) -> Any? {
         switch name {
         case "capitalized":
             return self.capitalized
@@ -23,12 +42,19 @@ extension StringProtocol {
 extension String: HBMustacheMethods {}
 extension Substring: HBMustacheMethods {}
 
-protocol HBComparableSequence {
+/// Protocol for sequence that can be sorted
+private protocol HBComparableSequence {
     func runComparableMethod(_ name: String) -> Any?
 }
 
 extension Array: HBMustacheMethods {
-    func runMethod(_ name: String) -> Any? {
+    /// Apply method to Array.
+    ///
+    /// Methods available are `first`, `last`, `reversed`, `count` and for arrays
+    /// with comparable elements `sorted`.
+    /// - Parameter name: method name
+    /// - Returns: Result
+    public func runMethod(_ name: String) -> Any? {
         switch name {
         case "first":
             return self.first
@@ -59,7 +85,13 @@ extension Array: HBComparableSequence where Element: Comparable {
 }
 
 extension Dictionary: HBMustacheMethods {
-    func runMethod(_ name: String) -> Any? {
+    /// Apply method to Dictionary
+    ///
+    /// Methods available are `count`, `enumerated` and for dictionaries
+    /// with comparable keys `sorted`.
+    /// - Parameter name: method name
+    /// - Returns: Result
+    public func runMethod(_ name: String) -> Any? {
         switch name {
         case "count":
             return self.count
@@ -86,12 +118,21 @@ extension Dictionary: HBComparableSequence where Key: Comparable {
 }
 
 extension FixedWidthInteger {
-    func runMethod(_ name: String) -> Any? {
+    /// Apply method to FixedWidthInteger
+    ///
+    /// Methods available are `plusone`, `minusone`, `odd`, `even`
+    /// - Parameter name: method name
+    /// - Returns: Result
+    public func runMethod(_ name: String) -> Any? {
         switch name {
         case "plusone":
             return self + 1
         case "minusone":
             return self - 1
+        case "even":
+            return (self & 1) == 0
+        case "odd":
+            return (self & 1) == 1
         default:
             return nil
         }
diff --git a/Tests/HummingbirdMustacheTests/MethodTests.swift b/Tests/HummingbirdMustacheTests/MethodTests.swift
index 505e8e2..6a8ac17 100644
--- a/Tests/HummingbirdMustacheTests/MethodTests.swift
+++ b/Tests/HummingbirdMustacheTests/MethodTests.swift
@@ -1,5 +1,5 @@
 import XCTest
-@testable import HummingbirdMustache
+import HummingbirdMustache
 
 final class MethodTests: XCTestCase {
     func testLowercased() throws {