add docs on shorthands