Index: sasmodels/models/core_shell_cylinder.py
===================================================================
--- sasmodels/models/core_shell_cylinder.py	(revision 2d81cfe3be42579d563407fb9275b7b516fee234)
+++ sasmodels/models/core_shell_cylinder.py	(revision e31b19a46729ff0f8f1a5eb9847f69524a6ed1d3)
@@ -5,5 +5,11 @@
 The output of the 2D scattering intensity function for oriented core-shell
 cylinders is given by (Kline, 2006 [#kline]_). The form factor is normalized
-by the particle volume.
+by the particle volume. Note that in this model the shell envelops the entire
+core so that besides a "sleeve" around the core, the shell also provides two
+flat end caps of thickness = shell thickness. In other words the length of the
+total cyclinder is the length of the core cylinder plus twice the thickness of
+the shell. If no end caps are desired one should use the
+:ref:`core-shell-bicelle` and set the thickness of the end caps (in this case
+the "thick_face") to zero.
 
 .. math::
@@ -33,6 +39,6 @@
 
 and $\alpha$ is the angle between the axis of the cylinder and $\vec q$,
-$V_s$ is the volume of the outer shell (i.e. the total volume, including
-the shell), $V_c$ is the volume of the core, $L$ is the length of the core,
+$V_s$ is the total volume (i.e. including both the core and the outer shell),
+$V_c$ is the volume of the core, $L$ is the length of the core,
 $R$ is the radius of the core, $T$ is the thickness of the shell, $\rho_c$
 is the scattering length density of the core, $\rho_s$ is the scattering
@@ -135,12 +141,4 @@
     return 0.5 * (ddd) ** (1. / 3.)
 
-def VR(radius, thickness, length):
-    """
-    Returns volume ratio
-    """
-    whole = pi * (radius + thickness) ** 2 * (length + 2 * thickness)
-    core = pi * radius ** 2 * length
-    return whole, whole - core
-
 def random():
     outer_radius = 10**np.random.uniform(1, 4.7)
Index: sasmodels/models/core_shell_sphere.py
===================================================================
--- sasmodels/models/core_shell_sphere.py	(revision dc76240c1dc8dcc0235d0432f3a909bea6e0c6a2)
+++ sasmodels/models/core_shell_sphere.py	(revision da1c8d14693f7a806280e49df578d46f9aa451d8)
@@ -89,15 +89,4 @@
     return radius + thickness
 
-def VR(radius, thickness):
-    """
-        Volume ratio
-        @param radius: core radius
-        @param thickness: shell thickness
-    """
-    return (1, 1)
-    whole = 4.0/3.0 * pi * (radius + thickness)**3
-    core = 4.0/3.0 * pi * radius**3
-    return whole, whole - core
-
 def random():
     outer_radius = 10**np.random.uniform(1.3, 4.3)
@@ -114,7 +103,4 @@
 tests = [
     [{'radius': 20.0, 'thickness': 10.0}, 'ER', 30.0],
-    # TODO: VR test suppressed until we sort out new product model
-    # and determine what to do with volume ratio.
-    #[{'radius': 20.0, 'thickness': 10.0}, 'VR', 0.703703704],
 
     # The SasView test result was 0.00169, with a background of 0.001
Index: sasmodels/models/fractal_core_shell.py
===================================================================
--- sasmodels/models/fractal_core_shell.py	(revision ef07e950965796e2a3a8156fcade98ce5e403001)
+++ sasmodels/models/fractal_core_shell.py	(revision eb3eb38c009cc70439ad74fa78055d6551981520)
@@ -88,5 +88,5 @@
     ["sld_shell",   "1e-6/Ang^2", 2.0,  [-inf, inf], "sld",    "Sphere shell scattering length density"],
     ["sld_solvent", "1e-6/Ang^2", 3.0,  [-inf, inf], "sld",    "Solvent scattering length density"],
-    ["volfraction", "",           1.0,  [0.0, inf],  "",       "Volume fraction of building block spheres"],
+    ["volfraction", "",           0.05,  [0.0, inf],  "",       "Volume fraction of building block spheres"],
     ["fractal_dim",    "",        2.0,  [0.0, 6.0],  "",       "Fractal dimension"],
     ["cor_length",  "Ang",      100.0,  [0.0, inf],  "",       "Correlation length of fractal-like aggregates"],
@@ -134,27 +134,21 @@
     return radius + thickness
 
-def VR(radius, thickness):
-    """
-        Volume ratio
-        @param radius: core radius
-        @param thickness: shell thickness
-    """
-    whole = 4.0/3.0 * pi * (radius + thickness)**3
-    core = 4.0/3.0 * pi * radius**3
-    return whole, whole-core
+tests = [[{'radius': 20.0, 'thickness': 10.0}, 'ER', 30.0],
 
-tests = [[{'radius': 20.0, 'thickness': 10.0}, 'ER', 30.0],
-         [{'radius': 20.0, 'thickness': 10.0}, 'VR', 0.703703704]]
-
-#         # The SasView test result was 0.00169, with a background of 0.001
-#         # They are however wrong as we now know.  IGOR might be a more
-#         # appropriate source. Otherwise will just have to assume this is now
-#         # correct and self generate a correct answer for the future. Until we
-#         # figure it out leave the tests commented out
-#         [{'radius': 60.0,
-#           'thickness': 10.0,
-#           'sld_core': 1.0,
-#           'sld_shell': 2.0,
-#           'sld_solvent': 3.0,
-#           'background': 0.0
-#          }, 0.015211, 692.84]]
+#         # At some point the SasView 3.x test result was deemed incorrect. The
+          #following tests were verified against NIST IGOR macros ver 7.850.
+          #NOTE: NIST macros do only provide for a polydispers core (no option
+          #for a poly shell or for a monodisperse core.  The results seemed
+          #extremely sensitive to the core PD, varying non monotonically all
+          #the way to a PD of 1e-6. From 1e-6 to 1e-9 no changes in the
+          #results were observed and the values below were taken using PD=1e-9.
+          #Non-monotonically = I(0.001)=188 to 140 to 177 back to 160 etc.
+         [{'radius': 20.0,
+           'thickness': 5.0,
+           'sld_core': 3.5,
+           'sld_shell': 1.0,
+           'sld_solvent': 6.35,
+           'volfraction': 0.05,
+           'background': 0.0},
+           [0.001,0.00291,0.0107944,0.029923,0.100726,0.476304],
+           [177.146,165.151,84.1596,20.1466,1.40906,0.00622666]]]
Index: sasmodels/models/hollow_cylinder.py
===================================================================
--- sasmodels/models/hollow_cylinder.py	(revision 2d81cfe3be42579d563407fb9275b7b516fee234)
+++ sasmodels/models/hollow_cylinder.py	(revision 455aaa1fbc231bb1caf309ca6419f0e3ffd5e19c)
@@ -1,6 +1,10 @@
 r"""
+Definition
+----------
+
 This model provides the form factor, $P(q)$, for a monodisperse hollow right
-angle circular cylinder (rigid tube) where the form factor is normalized by the
-volume of the tube (i.e. not by the external volume).
+angle circular cylinder (rigid tube) where the The inside and outside of the
+hollow cylinder are assumed to have the same SLD and the form factor is thus
+normalized by the volume of the tube (i.e. not by the total cylinder volume).
 
 .. math::
@@ -8,10 +12,16 @@
     P(q) = \text{scale} \left<F^2\right>/V_\text{shell} + \text{background}
 
-where the averaging $\left<\ldots\right>$ is applied only for the 1D calculation.
+where the averaging $\left<\ldots\right>$ is applied only for the 1D
+calculation. If Intensity is given on an absolute scale, the scale factor here
+is the volume fraction of the shell.  This differs from
+the :ref:`core-shell-cylinder` in that, in that case, scale is the volume
+fraction of the entire cylinder (core+shell). The application might be for a
+bilayer which wraps into a hollow tube and the volume fraction of material is
+all in the shell, whereas the :ref:`core-shell-cylinder` model might be used for
+a cylindrical micelle where the tails in the core have a different SLD than the
+headgroups (in the shell) and the volume fraction of material comes fromm the
+whole cyclinder.  NOTE: the hollow_cylinder represents a tube whereas the
+core_shell_cylinder includes a shell layer covering the ends (end caps) as well.
 
-The inside and outside of the hollow cylinder are assumed have the same SLD.
-
-Definition
-----------
 
 The 1D scattering intensity is calculated in the following way (Guinier, 1955)
@@ -48,6 +58,6 @@
 ----------
 
-L A Feigin and D I Svergun, *Structure Analysis by Small-Angle X-Ray and
-Neutron Scattering*, Plenum Press, New York, (1987)
+.. [#] L A Feigin and D I Svergun, *Structure Analysis by Small-Angle X-Ray and
+   Neutron Scattering*, Plenum Press, New York, (1987)
 
 Authorship and Verification
@@ -55,7 +65,7 @@
 
 * **Author:** NIST IGOR/DANSE **Date:** pre 2010
-* **Last Modified by:** Richard Heenan **Date:** October 06, 2016
-   (reparametrised to use thickness, not outer radius)
-* **Last Reviewed by:** Richard Heenan **Date:** October 06, 2016
+* **Last Modified by:** Paul Butler **Date:** September 06, 2018
+   (corrected VR calculation)
+* **Last Reviewed by:** Paul Butler **Date:** September 06, 2018
 """
 
@@ -120,5 +130,5 @@
     vol_total = pi*router*router*length
     vol_shell = vol_total - vol_core
-    return vol_shell, vol_total
+    return vol_total, vol_shell
 
 def random():
@@ -151,5 +161,5 @@
 tests = [
     [{}, 0.00005, 1764.926],
-    [{}, 'VR', 1.8],
+    [{}, 'VR', 0.55555556],
     [{}, 0.001, 1756.76],
     [{}, (qx, qy), 2.36885476192],
Index: sasmodels/models/hollow_rectangular_prism.py
===================================================================
--- sasmodels/models/hollow_rectangular_prism.py	(revision 2d81cfe3be42579d563407fb9275b7b516fee234)
+++ sasmodels/models/hollow_rectangular_prism.py	(revision 455aaa1fbc231bb1caf309ca6419f0e3ffd5e19c)
@@ -2,16 +2,12 @@
 # Note: model title and parameter table are inserted automatically
 r"""
-
-This model provides the form factor, $P(q)$, for a hollow rectangular
-parallelepiped with a wall of thickness $\Delta$.
-
-
 Definition
 ----------
 
-The 1D scattering intensity for this model is calculated by forming
-the difference of the amplitudes of two massive parallelepipeds
-differing in their outermost dimensions in each direction by the
-same length increment $2\Delta$ (Nayuk, 2012).
+This model provides the form factor, $P(q)$, for a hollow rectangular
+parallelepiped with a wall of thickness $\Delta$. The 1D scattering intensity
+for this model is calculated by forming the difference of the amplitudes of two
+massive parallelepipeds differing in their outermost dimensions in each
+direction by the same length increment $2\Delta$ (\ [#Nayuk2012]_ Nayuk, 2012).
 
 As in the case of the massive parallelepiped model (:ref:`rectangular-prism`),
@@ -61,8 +57,9 @@
   \rho_\text{solvent})^2 \times P(q) + \text{background}
 
-where $\rho_\text{p}$ is the scattering length of the parallelepiped,
-$\rho_\text{solvent}$ is the scattering length of the solvent,
+where $\rho_\text{p}$ is the scattering length density of the parallelepiped,
+$\rho_\text{solvent}$ is the scattering length density of the solvent,
 and (if the data are in absolute units) *scale* represents the volume fraction
-(which is unitless).
+(which is unitless) of the rectangular shell of material (i.e. not including
+the volume of the solvent filled core).
 
 For 2d data the orientation of the particle is required, described using
@@ -73,6 +70,7 @@
 
 For 2d, constraints must be applied during fitting to ensure that the inequality
-$A < B < C$ is not violated, and hence the correct definition of angles is preserved. The calculation will not report an error,
-but the results may be not correct.
+$A < B < C$ is not violated, and hence the correct definition of angles is
+preserved. The calculation will not report an error if the inequality is *not*
+preserved, but the results may be not correct.
 
 .. figure:: img/parallelepiped_angle_definition.png
@@ -99,5 +97,13 @@
 ----------
 
-R Nayuk and K Huber, *Z. Phys. Chem.*, 226 (2012) 837-854
+.. [#Nayuk2012] R Nayuk and K Huber, *Z. Phys. Chem.*, 226 (2012) 837-854
+
+
+Authorship and Verification
+----------------------------
+
+* **Author:** Miguel Gonzales **Date:** February 26, 2016
+* **Last Modified by:** Paul Kienzle **Date:** December 14, 2017
+* **Last Reviewed by:** Paul Butler **Date:** September 06, 2018
 """
 
Index: sasmodels/models/hollow_rectangular_prism_thin_walls.py
===================================================================
--- sasmodels/models/hollow_rectangular_prism_thin_walls.py	(revision 2d81cfe3be42579d563407fb9275b7b516fee234)
+++ sasmodels/models/hollow_rectangular_prism_thin_walls.py	(revision 6e7d7b66fc1ec444c4e30ac47db7bbcdc554ecc3)
@@ -2,14 +2,12 @@
 # Note: model title and parameter table are inserted automatically
 r"""
+Definition
+----------
+
 
 This model provides the form factor, $P(q)$, for a hollow rectangular
 prism with infinitely thin walls. It computes only the 1D scattering, not the 2D.
-
-
-Definition
-----------
-
 The 1D scattering intensity for this model is calculated according to the
-equations given by Nayuk and Huber (Nayuk, 2012).
+equations given by Nayuk and Huber\ [#Nayuk2012]_.
 
 Assuming a hollow parallelepiped with infinitely thin walls, edge lengths
@@ -55,8 +53,8 @@
   I(q) = \text{scale} \times V \times (\rho_\text{p} - \rho_\text{solvent})^2 \times P(q)
 
-where $V$ is the volume of the rectangular prism, $\rho_\text{p}$
-is the scattering length of the parallelepiped, $\rho_\text{solvent}$
-is the scattering length of the solvent, and (if the data are in absolute
-units) *scale* represents the volume fraction (which is unitless).
+where $V$ is the surface area of the rectangular prism, $\rho_\text{p}$
+is the scattering length density of the parallelepiped, $\rho_\text{solvent}$
+is the scattering length density of the solvent, and (if the data are in
+absolute units) *scale* is related to the total surface area.
 
 **The 2D scattering intensity is not computed by this model.**
@@ -67,5 +65,5 @@
 
 Validation of the code was conducted  by qualitatively comparing the output
-of the 1D model to the curves shown in (Nayuk, 2012).
+of the 1D model to the curves shown in (Nayuk, 2012\ [#Nayuk2012]_).
 
 
@@ -73,5 +71,13 @@
 ----------
 
-R Nayuk and K Huber, *Z. Phys. Chem.*, 226 (2012) 837-854
+.. [#Nayuk2012] R Nayuk and K Huber, *Z. Phys. Chem.*, 226 (2012) 837-854
+
+
+Authorship and Verification
+----------------------------
+
+* **Author:** Miguel Gonzales **Date:** February 26, 2016
+* **Last Modified by:** Paul Kienzle **Date:** October 15, 2016
+* **Last Reviewed by:** Paul Butler **Date:** September 07, 2018
 """
 
Index: sasmodels/models/spherical_sld.py
===================================================================
--- sasmodels/models/spherical_sld.py	(revision 2d81cfe3be42579d563407fb9275b7b516fee234)
+++ sasmodels/models/spherical_sld.py	(revision 5601947b596b5a6e24ccffd7b45469b40ae22f9d)
@@ -1,3 +1,6 @@
 r"""
+Definition
+----------
+
 Similarly to the onion, this model provides the form factor, $P(q)$, for
 a multi-shell sphere, where the interface between the each neighboring
@@ -16,14 +19,15 @@
 interface. The form factor is normalized by the total volume of the sphere.
 
-Interface shapes are as follows::
+Interface shapes are as follows:
 
     0: erf($\nu z$)
+    
     1: Rpow($z^\nu$)
+    
     2: Lpow($z^\nu$)
+    
     3: Rexp($-\nu z$)
+    
     4: Lexp($-\nu z$)
-
-Definition
-----------
 
 The form factor $P(q)$ in 1D is calculated by:
@@ -174,8 +178,18 @@
     when $P(Q) * S(Q)$ is applied.
 
+
 References
 ----------
-L A Feigin and D I Svergun, Structure Analysis by Small-Angle X-Ray
-and Neutron Scattering, Plenum Press, New York, (1987)
+
+.. [#] L A Feigin and D I Svergun, Structure Analysis by Small-Angle X-Ray
+   and Neutron Scattering, Plenum Press, New York, (1987)
+
+
+Authorship and Verification
+----------------------------
+
+* **Author:** Jae-Hie Cho **Date:** Nov 1, 2010
+* **Last Modified by:** Paul Kienzle **Date:** Dec 20, 2016
+* **Last Reviewed by:** Paul Butler **Date:** September 8, 2018
 """
 
Index: sasmodels/models/vesicle.py
===================================================================
--- sasmodels/models/vesicle.py	(revision ef07e950965796e2a3a8156fcade98ce5e403001)
+++ sasmodels/models/vesicle.py	(revision b4776059692723f870409527b8054b2a8a5e6797)
@@ -3,5 +3,9 @@
 ----------
 
-The 1D scattering intensity is calculated in the following way (Guinier, 1955)
+This model provides the form factor, *P(q)*, for an unilamellar vesicle and is
+effectively identical to the hollow sphere reparameterized to be
+more intuitive for a vesicle and normalizing the form factor by the volume of
+the shell. The 1D scattering intensity is calculated in the following way
+(Guinier,1955\ [#Guinier1955]_)
 
 .. math::
@@ -53,10 +57,14 @@
 ----------
 
-A Guinier and G. Fournet, *Small-Angle Scattering of X-Rays*, John Wiley and
-Sons, New York, (1955)
+.. [#Guinier1955] A Guinier and G. Fournet, *Small-Angle Scattering of X-Rays*, John Wiley and
+   Sons, New York, (1955)
+
+
+Authorship and Verification
+----------------------------
 
 * **Author:** NIST IGOR/DANSE **Date:** pre 2010
 * **Last Modified by:** Paul Butler **Date:** March 20, 2016
-* **Last Reviewed by:** Paul Butler **Date:** March 20, 2016
+* **Last Reviewed by:** Paul Butler **Date:** September 7, 2018
 """
 
@@ -65,8 +73,5 @@
 
 name = "vesicle"
-title = "This model provides the form factor, *P(q)*, for an unilamellar \
-    vesicle. This is model is effectively identical to the hollow sphere \
-    reparameterized to be more intuitive for a vesicle and normalizing the \
-    form factor by the volume of the shell."
+title = "Vesicle model representing a hollow sphere"
 description = """
     Model parameters:
