Add examples to public function docstrings

fixit/cli.py

@@ -14,6 +14,13 @@
 
 
 def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser for the fixit command-line interface.
+
+    Example:
+        parser = build_parser()
+        args = parser.parse_args(["wc", "hello world"])
+        assert args.command == "wc"
+    """
     parser = argparse.ArgumentParser(prog="fixit", description="A tiny toolbox to practice open source.")
     parser.add_argument("--version", action="version", version=f"fixit {__version__}")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -44,6 +51,11 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv=None) -> int:
+    """Run a fixit command and return its exit status.
+
+    Example:
+        main(["convert", "100", "c2f"]) prints 212.0 and returns 0.
+    """
     try:
         args = build_parser().parse_args(argv)
         if args.command == "wc":

fixit/convert.py

@@ -4,16 +4,36 @@
 
 
 def celsius_to_fahrenheit(c: float) -> float:
+    """Convert a temperature from Celsius to Fahrenheit.
+
+    Example:
+        celsius_to_fahrenheit(0) returns 32.
+    """
     return c * 9 / 5 + 32
 
 
 def fahrenheit_to_celsius(f: float) -> float:
+    """Convert a temperature from Fahrenheit to Celsius.
+
+    Example:
+        fahrenheit_to_celsius(32) returns 0.
+    """
     return (f - 32) * 5 / 9
 
 
 def km_to_miles(km: float) -> float:
+    """Convert kilometers to miles.
+
+    Example:
+        km_to_miles(1) returns approximately 0.6214.
+    """
     return km / KM_PER_MILE
 
 
 def miles_to_km(miles: float) -> float:
+    """Convert miles to kilometers.
+
+    Example:
+        miles_to_km(1) returns approximately 1.6093.
+    """
     return miles * KM_PER_MILE

fixit/jsonfmt.py

@@ -3,8 +3,12 @@
 
 
 def format_json(raw: str, indent: int = 2) -> str:
+    """Format a JSON string with indentation.
+
+    Example:
+        format_json('{"name":"Sam"}') returns '{\n  "name": "Sam"\n}'.
+    """
     try:
-        """Return pretty-printed JSON."""
         data = json.loads(raw)
         return json.dumps(data, indent=indent)
     except json.JSONDecodeError:

fixit/password.py

@@ -4,7 +4,11 @@
 
 
 def generate(length: int = 12, use_digits: bool = True, use_symbols: bool = False) -> str:
-    """Return a random password of the given length."""
+    """Generate a random password of the given length.
+
+    Example:
+        generate(4, use_digits=False) returns a 4-character password.
+    """
     if length <= 0:
         raise ValueError("Password length must be greater then 0!")
     chars = string.ascii_letters

fixit/textutils.py

@@ -2,10 +2,19 @@
 
 
 def is_palindrome(text: str) -> bool:
-    """Return True if text reads the same forwards and backwards."""
+    """Check whether text reads the same forwards and backwards.
+
+    Example:
+        is_palindrome("madam") returns True.
+        is_palindrome("hello") returns False.
+    """
     return text == text[::-1]
 
 
 def reverse_words(text: str) -> str:
-    """Reverse the order of words in text."""
+    """Reverse the order of words in text.
+
+    Example:
+        reverse_words("hello world") returns "world hello".
+    """
     return " ".join(reversed(text.split()))

fixit/wordcount.py

@@ -1,17 +1,33 @@
-import re
 """Word, line and character counting."""
 
+import re
+
 
 def count_words(text: str) -> int:
-    """Return the number of words in text."""
-    return len(re.split(r'\s+',text.strip()))
+    """Count the words in the given text.
+
+    Example:
+        count_words("hello world") returns 2.
+        count_words("one two three") returns 3.
+    """
+    return len(re.split(r'\s+', text.strip()))
 
 
 def count_lines(text: str) -> int:
-    """Return the number of lines in text."""
+    """Count the lines in the given text.
+
+    Example:
+        count_lines("hello\nworld") returns 2.
+        count_lines("hello") returns 1.
+    """
     return len(text.split("\n"))
 
 
 def count_chars(text: str) -> int:
-    """Return the number of characters in text."""
+    """Count the characters in the given text.
+
+    Example:
+        count_chars("hello") returns 5.
+        count_chars("hi!") returns 3.
+    """
     return len(text)