diff --git a/scripts/PassiveCable.jl b/scripts/PassiveCable.jl
index f7eae2d6e77ba4fc2f04d1b8f5129df47cbfc3f5..a5d714c894a2f0d1a4481a3dd9836440b9a16967 100644
--- a/scripts/PassiveCable.jl
+++ b/scripts/PassiveCable.jl
@@ -12,7 +12,12 @@ export cable_normalize, cable, rallpack1
 #     ∂g/∂x (0, t) = 1
 #     ∂g/∂x (L, t) = 0
 #
-# (This implementation converges slowly for small t)
+# Parameters:
+#     x, t, L:  as described above
+#   tol:  absolute error tolerance in result
+#
+# Return:
+#     g(x, t)
 
 function cable_normalized(x, t, L; tol=1e-8)
     if t<=0
@@ -32,7 +37,7 @@ function cable_normalized(x, t, L; tol=1e-8)
                 break
             end
         end
-	return ginf+sum
+        return ginf+sum
      end
 end
 
@@ -56,18 +61,37 @@ end
 #
 #     L:  length of cable
 #     r:  linear axial resistivity
-#     g:  linear membrane conductance
-#     c:  linear membrane capacitance.
+#     g:  linear membrane conductivity
+#     c:  linear membrane capacitance
 #     V:  membrane reversal potential
-#     I:  injected current on the left end (x = 0) of the cable.
+#     I:  injected axial current on the left end (x = 0) of the cable.
+#
+# Note that r, g and c are specific 1-d quantities that differ from
+# the cable resistivity r_L, specific membrane conductivity ḡ and
+# specific membrane capacitance c_m as used elsewhere. If the
+# cross-sectional area is A and cable circumference is f, then
+# these quantities are related by:
+#
+#     r = r_L/A
+#     g = ḡ·f
+#     c = c_m·f
+#
+# Parameters:
+#     x:  displacement along cable
+#     t:  time
+#     L, lambda, tau, r, V, I:  as described above
+#   tol:  absolute error tolerance in result
+#
+# Return:
+#     computed potential at (x,t) on cable.
 
 function cable(x, t, L, lambda, tau, r, V, I; tol=1e-8)
     scale = -I*r*lambda;
     if scale == 0
-	return V
+        return V
     else
         tol_n = abs(tol/scale)
-	return scale*cable_normalized(x/lambda, t/tau, L/lambda, tol=tol_n) + V
+        return scale*cable_normalized(x/lambda, t/tau, L/lambda, tol=tol_n) + V
     end
 end
 
@@ -82,8 +106,21 @@ end
 #     d  = 1 µm     cable diameter
 #     EM = -65 mV   reversal potential
 #     I  = 0.1 nA   injected current
-#     L  = 1 mm     cable length 
+#     L  = 1 mm     cable length.
+#
+# (This notation aligns with that used in the Rallpacks paper.)
+#
+# Note that the injected current as described in the Rallpack model
+# is trans-membrane, not axial. Consequently we need to swap the
+# sign on I when passing to the cable function.
+#
+# Parameters:
+#     x:  displacement along cable [m]
+#     t:  time [s]
+#   tol:  absolute tolerance for reported potential.
 #
+# Return:
+#     computed potential at (x,t) on cable.
 
 function rallpack1(x, t; tol=1e-8)
     RA = 1
@@ -101,4 +138,4 @@ function rallpack1(x, t; tol=1e-8)
     return cable(x, t, L, lambda, tau, r, EM, I, tol=tol)
 end
 
-end #module
+end # module PassiveCable
diff --git a/scripts/README.md b/scripts/README.md
index bd8c6111742d84c770da7a89bd0b9ce2a8f22bab..373f9f1330840c7cddf9fcf264d92f943c55c33b 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -1,5 +1,4 @@
-tsplot
-======
+#tsplot
 
 The `tsplot` script is a wrapper around matplotlib for displaying a collection of
 time series plots.
@@ -78,8 +77,7 @@ of the timeseries data.
 Use the `-o` or `--output` option to save the plot as an image, instead of
 displaying it interactively.
 
-profstats
-=========
+#profstats
 
 `profstats` collects the profiling data output from multiple MPI ranks and performs
 a simple statistical summary.
@@ -92,8 +90,7 @@ are reported instead.
 
 Output is in CSV format.
 
-PassiveCable.jl
-===============
+#PassiveCable.jl
 
 Compute analytic solutions to the simple passive cylindrical dendrite cable
 model with step current injection at one end from t=0.