unit: fix up package docs

unit/doc.go

@@ -7,77 +7,117 @@
 // Package unit provides a set of types and constants that facilitate
 // the use of the International System of Units (SI).
 //
-// Unit provides two main functionalities.
+// The unit package provides two main functionalities: compile-time type-safe
+// base SI units and common derived units; and a system for dynamically
+// extensible user-defined units.
+//
+// Static SI units
+//
+// This package provides a number of types representing either an SI base
+// unit or a common combination of base units, named for the physical quantity
+// it represents (Length, Mass, Pressure, etc.). Each type is defined from
+// float64. The value of the float64 represents the quantity of that unit as
+// expressed in SI base units (Kilogram, Meter, Pascal, etc.). For example,
+//
+// 	height := 1.6 * unit.Meter
+// 	acc := unit.Acceleration(9.8)
 //
-// 1)
-// It provides a number of types representing either an SI base unit
-// or a common combination of base units, named for the unit it
-// represents (Length, Mass, Pressure, etc.). Each type has
-// a float64 as the underlying unit, and its value represents the
-// number of that underlying unit (Kilogram, Meter, Pascal, etc.).
-// For example,
-//		height := 1.6 * unit.Meter
-//		acc := unit.Acceleration(9.8)
 // creates a variable named 'height' with a value of 1.6 meters, and
 // a variable named 'acc' with a value of 9.8 meters per second squared.
 // These types can be used to add compile-time safety to code. For
 // example,
-//		func UnitDensity(t unit.Temperature, pressure unit.Pressure) (unit.Density){
-//			...
-//		}
-//		func main(){
-//			t := 300 * unit.Kelvin
-//			p := 5 * unit.Bar
-//			rho := UnitDensity(p, t) // compile-time error
-//		}
+//
+// 	func unitVolume(t unit.Temperature, p unit.Pressure) unit.Volume {
+// 		...
+// 	}
+//
+// 	func main(){
+// 		t := 300 * unit.Kelvin
+// 		p := 500 * unit.Kilopascal
+// 		v := unitVolume(p, t) // compile-time error
+// 	}
+//
 // gives a compile-time error (temperature type does not match pressure type)
 // while the corresponding code using float64 runs without error.
-//		func Float64Density(temperature, pressure float64) (float64){
-//			...
-//		}
-//		func main(){
-//			t := 300.0 // degrees kelvin
-//			p := 50000.0 // Pascals
-//			rho := Float64Density(p, t) // no error
-//		}
+//
+// 	func float64Volume(temperature, pressure float64) float64 {
+// 		...
+// 	}
+//
+// 	func main(){
+// 		t := 300.0 // Kelvin
+// 		p := 500000.0 // Pascals
+// 		v := float64Volume(p, t) // no error
+// 	}
+//
 // Many types have constants defined representing named SI units (Meter,
-// Kilogram, etc. ) or SI derived units (Bar, Hz, etc.). The Unit package
+// Kilogram, etc. ) or SI derived units (Pascal, Hz, etc.). The unit package
 // additionally provides untyped constants for SI prefixes, so the following
 // are all equivalent.
-//		l := 0.001 * unit.Meter
-//		k := 1 * unit.Milli * unit.Meter
-//		j := unit.Length(0.001)
 //
-// 2)
-// Unit provides the type "Unit", meant to represent a general dimensional
-// value. unit.Unit can be used to help prevent errors of dimensionality
-// when multiplying or dividing dimensional numbers. This package also
-// provides the "Uniter" interface which is satisfied by any type which can
-// be converted to a unit. New varibles of type Unit can be created with
-// the New function and the Dimensions map. For example, the code
-//		acc := New(9.81, Dimensions{LengthDim:1, TimeDim: -2})
-// creates a variable "acc" which has a value of 9.81 m/s^2. Methods of
+// 	l := 0.001 * unit.Meter
+// 	k := 1 * unit.Milli * unit.Meter
+// 	j := unit.Length(0.001)
+//
+// Additional SI-derived static units can also be defined by adding types that
+// satisfy the Uniter interface described below.
+//
+// Dynamic user-extensible unit system
+//
+// The unit package also provides the Unit type, a representation of a general
+// dimensional value. Unit can be used to help prevent errors of dimensionality
+// when multiplying or dividing dimensional numbers defined a run time. New
+// variables of type Unit can be created with the New function and the
+// Dimensions map. For example, the code
+//
+// 	rate := unit.New(1 * unit.Milli, Dimensions{MoleDim: 1, TimeDim: -1})
+//
+// creates a variable "rate" which has a value of 1e-3 mol/s. Methods of
 // unit can be used to modify this value, for example:
-// 		acc.Mul(1.0 * unit.Kilogram).Mul(1 * unit.Meter)
+//
+// 	rate.Mul(1 * unit.Centimeter).Div(1 * unit.Millivolt)
+//
 // To convert the unit back into a typed float64 value, the From methods
 // of the dimensional types should be used. From will return an error if the
 // dimensions do not match.
-// 		var energy unit.Energy
-//		err := (*energy).From(acc)
+//
+// 	var energy unit.Energy
+// 	err := energy.From(acc)
+//
 // Domain-specific problems may need custom dimensions, and for this purpose
 // NewDimension should be used to help avoid accidental overlap between
 // packages. For example, results from a blood test may be measured in
 // "White blood cells per slide". In this case, NewDimension should be
 // used to create a 'WhiteBloodCell' dimension. NewDimension takes in a
 // string which will be used for printing that dimension, and will return
-// a unique dimension number. NewDimension should not be
-// used, however, to create the unit of 'Slide', because in this case slide
-// is just a measurement of area. Instead, a constant could be defined.
-//		const Slide unit.Area =  0.001875 // m^2
-// Note that Unit cannot catch all errors related to dimensionality.
+// a unique dimension number.
+//
+// 	wbc := unit.NewDimension("WhiteBloodCell")
+//
+// NewDimension should not be used, however, to create the unit of 'Slide',
+// because in this case slide is just a measurement of liquid volume. Instead,
+// a constant could be defined.
+//
+// 	const Slide unit.Volume =  0.1 * unit.Microliter
+//
+// Note that unit cannot catch all errors related to dimensionality.
 // Different physical ideas are sometimes expressed with the same dimensions
-// and Unit is incapable of catching these mismatches. For example, energy and
+// and unit is incapable of catching these mismatches. For example, energy and
 // torque are both expressed as force times distance (Newton-meters in SI),
 // but it is wrong to say that a torque of 10 N-m is the same as 10 J, even
-// though the dimensions agree.
+// though the dimensions agree. Despite this, using the defined types to
+// represent units can help to catch errors at compile-time. For example,
+//
+// 	type Torque float64
+//
+// 	func (t Torque) Unit() *Unit {...
+//
+// allows you to define a statically typed function like so
+//
+// 	func LeverLength(apply unit.Force, want Torque) unit.Length {
+//		return unit.Length(float64(want)/float64(apply))
+// 	}
+//
+// This will prevent an energy value being provided to LeverLength in place
+// of a torque value.
 package unit // import "gonum.org/v1/gonum/unit"