Merge pull request #94 from braboj/codex/add-descriptive-headers-to-example-files

Add structured headers to exception examples

Author: braboj

examples/14_exceptions/__init__.py

@@ -0,0 +1,4 @@
+# Exception Example Package
+# --------------------------------------------------------------------------------
+# Contains modules demonstrating custom exception hierarchies and handling
+# patterns.

examples/14_exceptions/demo_generation.py

@@ -1,3 +1,8 @@
+# Old-Style Exception Generation
+# --------------------------------------------------------------------------------
+# Shows what happens when raising an exception class that does not inherit from
+# BaseException.
+
 # class NewStyleException(Exception): pass
 #
 # try:

examples/14_exceptions/demo_handlers.py

@@ -1,3 +1,8 @@
+# Exception Handling Styles
+# --------------------------------------------------------------------------------
+# Compares using a single except clause against multiple specific handlers for
+# related errors.
+
 def raise_overflow_error():
     raise OverflowError
 

examples/14_exceptions/exception_catch_multiple.py

@@ -1,4 +1,7 @@
-# Example: Catch Multiple Exceptions with junior Single Except Block
+# Grouped Exception Handling
+# --------------------------------------------------------------------------------
+# Illustrates catching different members of an exception hierarchy with one
+# except block.
 
 
 from exception_hierarchy import *

examples/14_exceptions/exception_chaining.py

@@ -1,4 +1,7 @@
-# Example: Exception Chaining
+# Exception Chaining
+# --------------------------------------------------------------------------------
+# Demonstrates explicit and implicit chaining of exceptions to preserve the
+# original error context.
 
 class MyException(Exception):
     pass

examples/14_exceptions/exception_files.txt

@@ -1,3 +1,7 @@
+# Exception Files Layout
+# --------------------------------------------------------------------------------
+# Displays a sample directory tree for keeping custom error definitions organized.
+
 src/
  ├─ socket
  │  ├─ __init__.py

examples/14_exceptions/exception_flow_with_try_except.py

@@ -1,4 +1,6 @@
-# Example: Exception Flow with try-except statements
+# Control Flow with try/except
+# --------------------------------------------------------------------------------
+# Shows normal execution resuming after errors are caught and handled.
 def func_a(x):
     # Function uses and returns only positive values
     if x < 0:

examples/14_exceptions/exception_flow_without_try_except.py

@@ -1,4 +1,6 @@
-# Example of exception flow without try/except statements
+# Control Flow without try/except
+# --------------------------------------------------------------------------------
+# Illustrates manual error checking when no exception handlers are used.
 
 def func_a(x):
     # Function uses and returns only positive values

examples/14_exceptions/exception_handling.py

@@ -1,4 +1,6 @@
-# Example: Exception Handling with try-except statements
+# Structured Exception Handling
+# --------------------------------------------------------------------------------
+# Uses try/except/else/finally blocks to handle expected and unexpected errors.
 
 import time
 

examples/14_exceptions/exception_hierarchy.py

@@ -1,4 +1,7 @@
-# Example: Exception Hierarchy in junior Package
+# Custom Exception Hierarchy
+# --------------------------------------------------------------------------------
+# Defines a family of related custom exceptions and demonstrates raising each
+# member of the hierarchy.
 
 class SocketError(Exception):