Improve MaterialX doc strings (#97)

reference/open_pbr_surface.mtlx

@@ -6,83 +6,83 @@
   <nodedef name="ND_open_pbr_surface_surfaceshader" node="open_pbr_surface" nodegroup="pbr" version="0.1" isdefaultversion="true"
            doc="OpenPBR Surface Shading Model">
     <input name="base_weight" type="float" value="1.0" uimin="0.0" uimax="1.0" uiname="Base Weight" uifolder="Base"
-           doc="Multiplier on the intensity of the diffuse reflection." />
+           doc="Multiplier on the intensity of the reflection from the diffuse and metallic base." />
     <input name="base_color" type="color3" value="0.8, 0.8, 0.8" uimin="0,0,0" uimax="1,1,1" uiname="Base Color" uifolder="Base"
-           doc="Color of the diffuse reflection." />    
+           doc="Color of the reflection from the diffuse and metallic base." />
     <input name="base_roughness" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Base Roughness" uifolder="Base" uiadvanced="true"
-           doc="Roughness of the diffuse reflection. Higher values cause the surface to appear flatter and darker." />
+           doc="Roughness of the diffuse reflection. Higher values cause the surface to appear flatter." />
     <input name="base_metalness" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Base Metalness" uifolder="Base"
-           doc="Specifies how metallic the material appears. At its maximum, the surface behaves like a metal, using fully specular reflection and complex fresnel." />
+           doc="Specifies how metallic the base material appears (dials the base from pure dielectric to pure metal)." />
     <input name="specular_weight" type="float" value="1" uimin="0.0" uimax="1.0" uiname="Specular Weight" uifolder="Specular"
            doc="Multiplier on the intensity of the specular reflection." />
     <input name="specular_color" type="color3" value="1, 1, 1" uimin="0,0,0" uimax="1,1,1" uiname="Specular Color" uifolder="Specular"
-           doc="Color tint on the specular reflection." />
+           doc="Color of the specular reflection (controls the physical edge-tint for metals, and a non-physical overall tint for dielectrics)." />
     <input name="specular_roughness" type="float" value="0.2" uimin="0.0" uimax="1.0" uiname="Specular Roughness" uifolder="Specular"
            doc="The roughness of the specular reflection. Lower numbers produce sharper reflections, higher numbers produce blurrier reflections." />
     <input name="specular_ior" type="float" value="1.5" uimin="0.0" uisoftmin="1.0" uisoftmax="3.0" uiname="Index of Refraction" uifolder="Specular"
-           doc="Index of refraction for specular reflection." />
+           doc="Index of refraction of the dielectric base." />
     <input name="specular_anisotropy" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Specular Anisotropy" uifolder="Specular" uiadvanced="true"
-           doc="The directional bias of reflected and transmitted light resulting in materials appearing rougher or glossier in certain directions." />
+           doc="The directional bias of the roughness of the metal/dielectric base, resulting in increasingly stretched highlights along the tangent direction." />
     <input name="specular_rotation" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Specular Rotation" uifolder="Specular" uiadvanced="true"
-           doc="Rotation of the axis of specular anisotropy around the surface normal." />
+           doc="Rotation of the axis of specular roughness anisotropy around the surface normal." />
     <input name="transmission_weight" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Transmission Weight" uifolder="Transmission" uiadvanced="true"
-           doc="Transmission of light through the surface for materials such as glass or water. The greater the value the more transparent the material." />
+           doc="Mixture weight between the transparent and opaque dielectric base. The greater the value the more transparent the material." />
     <input name="transmission_color" type="color3" value="1, 1, 1" uimin="0,0,0" uimax="1,1,1" uiname="Transmission Color" uifolder="Transmission" uiadvanced="true"
-           doc="Color tint on the transmitted light." />
+           doc="Controls color of the transparent base due to Beer's law volumetric absorption under the surface (reverts to a non-physical tint when transmission_depth is zero)." />
     <input name="transmission_depth" type="float" value="0" uimin="0.0" uisoftmax="100.0" uiname="Transmission Depth" uifolder="Transmission" uiadvanced="true"
-           doc="Specifies the distance light travels inside the material before its becomes exactly the transmission color according to Beer's law." />
+           doc="Specifies the distance light travels inside the transparent base before it becomes exactly the transmission_color according to Beer's law." />
     <input name="transmission_scatter" type="color3" value="0, 0, 0" uimin="0,0,0" uimax="1,1,1" uiname="Transmission Scatter" uifolder="Transmission" uiadvanced="true"
-           doc="Scattering coefficient of the interior medium. Suitable for a large body of liquid or one that is fairly thick, such as an ocean, honey, ice, or frosted glass." />
+           doc="Controls the color of light volumetrically scattered inside the transparent base. Suitable for materials with visually significant scattering such as honey, fruit juice, murky water, opalescent glass, or milky glass." />
     <input name="transmission_scatter_anisotropy" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Transmission Anisotropy" uifolder="Transmission" uiadvanced="true"
-           doc="The amount of directional bias, or anisotropy, of the scattering." />
+           doc="The amount of directional bias, or anisotropy, of the volumetric scattering in the transparent base." />
     <input name="transmission_dispersion" type="float" value="0" uimin="0.0" uisoftmax="100.0" uiname="Transmission Dispersion" uifolder="Transmission" uiadvanced="true"
-           doc="Dispersion amount, describing how much the index of refraction varies across wavelengths." />
+           doc="Dispersion amount, describing how much the dielectric index of refraction varies across wavelengths." />
     <input name="transmission_extra_roughness" type="float" value="0" uimin="-1.0" uisoftmin="0.0" uimax="1.0" uiname="Transmission Roughness" uifolder="Transmission" uiadvanced="true"
-           doc="Additional roughness on top of specular roughness. Positive values blur refractions more than reflections, and negative values blur refractions less." />
+           doc="Additional roughness on top of specular roughness, applied to refracted rays. Positive values blur refractions more than reflections, and negative values blur refractions less." />
     <input name="subsurface_weight" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Subsurface" uifolder="Subsurface Weight" uiadvanced="true"
-           doc="The blend between diffuse reflection and subsurface scattering. A value of 1.0 indicates full subsurface scattering and a value 0 for diffuse reflection only." />
+           doc="Mixture weight which dials the opaque dielectric base between diffuse reflection and subsurface scattering. A value of 1.0 indicates full subsurface scattering and a value 0 for diffuse reflection only." />
     <input name="subsurface_color" type="color3" value="0.8, 0.8, 0.8" uimin="0,0,0" uimax="1,1,1" uiname="Subsurface Color" uifolder="Subsurface" uiadvanced="true"
-           doc="The color of the subsurface scattering effect." />
+           doc="The overall reflected color of the subsurface scattering effect." />
     <input name="subsurface_radius" type="float" value="1" uimin="0.0" uisoftmax="10.0" uiname="Subsurface Radius" uifolder="Subsurface" uiadvanced="true"
-           doc="The mean free path, i.e. the average distance which light can travel before being scattered or absorbed inside the surface." />
+           doc="Length scale of the subsurface diffusion blur profile on the surface." />
     <input name="subsurface_radius_scale" type="color3" value="1, 1, 1" uimin="0,0,0" uimax="1,1,1" uiname="Subsurface Radius Scale" uifolder="Subsurface" uiadvanced="true"
-           doc="Per-channel scale factor for the subsurface radius value." />
+           doc="RGB multiplier to subsurface_radius, giving the per-channel diffusion blur profile size." />
     <input name="subsurface_anisotropy" type="float" value="0" uimin="-1.0" uimax="1.0" uiname="Subsurface Anisotropy" uifolder="Subsurface" uiadvanced="true"
-           doc="The direction of subsurface scattering. 0 scatters light evenly, positive values scatter forward and negative values scatter backward." />
+           doc="Controls the phase-function of subsurface scattering, where zero scatters light evenly, positive values scatter forward, and negative values scatter backward." />
     <input name="fuzz_weight" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Fuzz Weight" uifolder="Fuzz" uiadvanced="true"
-           doc="The weight of a fuzz layer that can be used to approximate microfibers or fabrics such as velvet and satin." />
+           doc="The weight of a fuzz layer that can be used to approximate microfibers, for fabrics such as velvet and satin as well as dust grains." />
     <input name="fuzz_color" type="color3" value="1, 1, 1" uimin="0,0,0" uimax="1,1,1" uiname="Fuzz Color" uifolder="Fuzz" uiadvanced="true"
            doc="The color of the fuzz layer." />
     <input name="fuzz_roughness" type="float" value="0.3" uimin="0.0" uimax="1.0" uiname="Fuzz Roughness" uifolder="Fuzz" uiadvanced="true"
            doc="The roughness of the fuzz layer." />
     <input name="coat_weight" type="float" value="0" uimin="0.0" uimax="1.0" uiname="Coat Weight" uifolder="Coat"
            doc="The weight of a reflective clear-coat layer on top of the material. Use for materials such as car paint or an oily layer." />
     <input name="coat_color" type="color3" value="1, 1, 1" uimin="0,0,0" uimax="1,1,1" uiname="Coat Color" uifolder="Coat"
-           doc="The color of the clear-coat layer's transparency." />
+           doc="The color of the clear-coat layer's transparency, due to absorption in the coat." />
     <input name="coat_roughness" type="float" value="0.1" uimin="0.0" uimax="1.0" uiname="Coat Roughness" uifolder="Coat"
            doc="The roughness of the clear-coat reflections. The lower the value, the sharper the reflection." />
     <input name="coat_anisotropy" type="float" value="0.0" uimin="0.0" uimax="1.0" uiname="Coat Anisotropy" uifolder="Coat" uiadvanced="true"
-           doc="The amount of directional bias, or anisotropy, of the clear-coat layer." />
+           doc="The directional bias of the roughness of the clear-coat layer, resulting in increasingly stretched highlights along the coat tangent direction." />
     <input name="coat_rotation" type="float" value="0.0" uimin="0.0" uimax="1.0" uiname="Coat Rotation" uifolder="Coat" uiadvanced="true"
-           doc="The rotation of the anisotropic effect of the clear-coat layer." />
+           doc="Rotation of the axis of clear-coat roughness anisotropy around the coat normal." />
     <input name="coat_ior" type="float" value="1.5" uimin="0.0" uisoftmin="1.0" uisoftmax="3.0" uiname="Coat Index of Refraction" uifolder="Coat"
            doc="The index of refraction of the clear-coat layer." />
     <input name="coat_affect_color" type="float" value="0" uimin="0" uimax="1" uiname="Coat Affect Color" uifolder="Coat" uiadvanced="true"
-           doc="Controls the saturation of diffuse reflection and subsurface scattering below the clear-coat." />
+           doc="Controls the extra saturation of diffuse reflection and subsurface scattering below the clear-coat, due to bounces in the coat layer." />
     <input name="coat_affect_roughness" type="float" value="0" uimin="0" uimax="1" uiname="Coat Affect Roughness" uifolder="Coat" uiadvanced="true"
-           doc="Controls the roughness of the specular reflection in the layers below the clear-coat." />
+           doc="Controls the extra roughness of the specular reflection in the layers below the clear-coat." />
     <input name="thin_film_thickness" type="float" value="0" uimin="0.0" uisoftmax="2000.0" uiname="Thin Film Thickness" uifolder="Thin Film" uiadvanced="true"
-           doc="The thickness of the thin film layer on a surface. Use for materials such as multitone car paint or soap bubbles." />
+           doc="The thickness of the thin film layer on the base (in nanometers). Use for materials such as multi-tone car paint or soap bubbles." />
     <input name="thin_film_ior" type="float" value="1.5" uimin="0.0" uisoftmin="1.0" uisoftmax="3.0" uiname="Thin Film Index of Refraction" uifolder="Thin Film" uiadvanced="true"
-           doc="The index of refraction of the medium surrounding the material." />
+           doc="The index of refraction of the thin-film." />
     <input name="emission_luminance" type="float" value="0" uimin="0.0" uisoftmax="1.0" uiname="Emission Luminance" uifolder="Emission"
-           doc="The amount of emitted incandescent light." />
+           doc="The amount of emitted light, as a luminance in nits." />
     <input name="emission_color" type="color3" value="1, 1, 1" uimin="0,0,0" uimax="1,1,1" uiname="Emission Color" uifolder="Emission"
            doc="The color of the emitted light." />
     <input name="geometry_opacity" type="color3" value="1, 1, 1" uimin="0,0,0" uimax="1,1,1" uiname="Opacity" uifolder="Geometry"
            doc="The opacity of the entire material." />
     <input name="geometry_thin_walled" type="boolean" value="false" uiname="Thin Walled" uifolder="Geometry" uiadvanced="true"
-           doc="If true the surface is double-sided and represents an infinitely thin shell. Suitable for thin objects such as tree leaves or paper." />
+           doc="If true the surface is double-sided and represents an infinitesimally thin shell. Suitable for extremely geometrically thin objects such as leaves or paper." />
     <input name="geometry_normal" type="vector3" defaultgeomprop="Nworld" uiname="Normal" uifolder="Geometry"
            doc="Input geometric normal" />
     <input name="geometry_coat_normal" type="vector3" defaultgeomprop="Nworld" uiname="Coat Normal" uifolder="Geometry"