From ac6149094dd14b4c0d8e067f32d8403eb8761a7e Mon Sep 17 00:00:00 2001
From: Ethan Dalool <git@voussoir.net>
Date: Wed, 13 Jan 2021 16:37:28 -0800
Subject: [PATCH] Add a few docstrings, remove getpermission.py.

---
 voussoirkit/betterhelp.py    |  8 ++++++++
 voussoirkit/bytestring.py    |  4 ++++
 voussoirkit/fusker.py        | 22 ++++++++++++++++++++++
 voussoirkit/getpermission.py |  5 -----
 voussoirkit/interactive.py   |  3 +++
 5 files changed, 37 insertions(+), 5 deletions(-)
 delete mode 100644 voussoirkit/getpermission.py

diff --git a/voussoirkit/betterhelp.py b/voussoirkit/betterhelp.py
index ad97d9a..6aaa28c 100644
--- a/voussoirkit/betterhelp.py
+++ b/voussoirkit/betterhelp.py
@@ -11,6 +11,11 @@ HELPSTRINGS = {'', 'help', '-h', '--help'}
 # INTERNALS
 ################################################################################
 def can_use_bare(parser):
+    '''
+    Return true if the given parser has no required arguments, ie can run bare.
+    This is used to decide whether running `> myprogram.py` should show the
+    helptext or just run normally.
+    '''
     def is_required(action):
         # I found that positional arguments marked with nargs=* were still being
         # considered 'required', which is not what I want as far as can_use_bare
@@ -25,6 +30,9 @@ def can_use_bare(parser):
     return has_func and not has_required_args
 
 def can_use_bare_subparsers(subparser_action):
+    '''
+    Return a set of subparser names which can be used bare.
+    '''
     can_bares = set(
         sp_name for (sp_name, sp) in subparser_action.choices.items()
         if can_use_bare(sp)
diff --git a/voussoirkit/bytestring.py b/voussoirkit/bytestring.py
index b29c253..1d475d4 100644
--- a/voussoirkit/bytestring.py
+++ b/voussoirkit/bytestring.py
@@ -1,3 +1,7 @@
+'''
+This module provides integer constants for power-of-two byte size units, and
+functions for converting between ints and human-readable strings e.g. "1.2 GiB".
+'''
 import re
 import sys
 
diff --git a/voussoirkit/fusker.py b/voussoirkit/fusker.py
index ebc00b4..3c5b409 100644
--- a/voussoirkit/fusker.py
+++ b/voussoirkit/fusker.py
@@ -1,3 +1,25 @@
+'''
+Fusking is the act of generating many strings by using a template with a range
+of integers or a spinner of alternate strings.
+
+Ranges:
+    x[1-10]y -> x1y, x2y, x3y, x4y, x5y, x6y, x7y, x8y, x9y, x10y
+    x[01-10]y -> x01y, x02y, x03y, x04y, x05y, x06y, x07y, x08y, x09y, x10y
+
+Spinners:
+    x{alpha|beta|charlie}y -> xalphay, xbetay, xcharliey
+
+fusker.fusker('https://subdomain-{a|b|c}.website.com/image[01-99].jpg') ->
+(
+    'https://subdomain-a.website.com/image01.jpg',
+    'https://subdomain-a.website.com/image02.jpg',
+    'https://subdomain-a.website.com/image03.jpg',
+    ...
+    'https://subdomain-a.website.com/image99.jpg',
+    'https://subdomain-b.website.com/image01.jpg',
+    'https://subdomain-b.website.com/image02.jpg',
+)
+'''
 import collections
 import itertools
 import string
diff --git a/voussoirkit/getpermission.py b/voussoirkit/getpermission.py
deleted file mode 100644
index 2ede0d4..0000000
--- a/voussoirkit/getpermission.py
+++ /dev/null
@@ -1,5 +0,0 @@
-import warnings
-warnings.warn('Please switch to voussoirkit.interactive.getpermission')
-
-from voussoirkit import interactive
-getpermission = interactive.getpermission
diff --git a/voussoirkit/interactive.py b/voussoirkit/interactive.py
index d973105..75c9fdb 100644
--- a/voussoirkit/interactive.py
+++ b/voussoirkit/interactive.py
@@ -1,3 +1,6 @@
+'''
+This module provides functions for interactive command line UIs.
+'''
 ####################################################################################################
 ## ABC_CHOOSER #####################################################################################
 ####################################################################################################