From 38e3661dc5d69e4dc0270365dfa4ff6e9d2974f6 Mon Sep 17 00:00:00 2001
From: Patrick <patrick@elmer.ws>
Date: Mon, 6 Feb 2023 16:20:34 +0900
Subject: [PATCH] Added docstring to apply function

---
 soundchanger/change.py | 33 +++++++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 6 deletions(-)

diff --git a/soundchanger/change.py b/soundchanger/change.py
index 7635f0f..9877731 100644
--- a/soundchanger/change.py
+++ b/soundchanger/change.py
@@ -1,18 +1,40 @@
 import re
 
 
-def apply(changes, strings, categories={}, ignore_errors=True, apply=True, zero_characters=['∅']):
+def apply(
+    changes,
+    strings,
+    apply=True,
+    categories={},
+    ignore_errors=True,
+    zero_characters=['∅']):
     """
     Applies a sound change or a list of sound changes to a string or
     a list of given strings.
+
+    Accepts inputs of type str or list.
+    If the input value is of type str, the output will also be of type str.
+
+    Options:
+      - apply (default: True)
+            Whether or not the changes should be applied.
+      - categories (default: {})
+            Which categories will be detected.
+            For vowels it would be {'V'='aeiou'} or {'V'=['a', 'e', 'i', 'o', 'u']})
+      - ignore_errors (default: True)
+            If this option is set to `True`, any erroneous sound change will be skipped.
+            If set to `False`, a ValueError will be raised.
+      - zero_characters (default: ['∅'])
+            These characters will be removed in the changed words.
+            For example, `apply('h>∅', 'aha')` will return 'aa', not 'a∅a'.
     """
 
     if not apply:
         return strings
-    
+
     if isinstance(changes, str):
         changes = [changes]
-    
+
     return_str = isinstance(strings, str)
     if isinstance(strings, str):
         strings = [strings]
@@ -20,7 +42,6 @@ def apply(changes, strings, categories={}, ignore_errors=True, apply=True, zero_
         strings = strings.copy()
 
     for change in changes:
-        
         if validate_change(change, ignore_errors=ignore_errors) == False:
             continue
 
@@ -33,7 +54,7 @@ def apply(changes, strings, categories={}, ignore_errors=True, apply=True, zero_
 
         for i, string in enumerate(strings):
             strings[i] = re.sub(pattern, replacement, f"#{string}#").strip('#')
-    
+
     if return_str:
         return strings[0]
     return strings
@@ -59,7 +80,7 @@ def convert_change_to_regex(change, categories, zero_characters):
         change = re.sub(f'((?<=,){k}|{k}(?=,))', '|'.join(v), change)
         # Replacements of categories anywhere else
         change = change.replace(k, '('+'|'.join(v)+')')
-    
+
     # Remove zero characters
     for char in zero_characters:
         change = change.replace(char, '')