document the 'weight' option