rarity argument support and documentation
update documentation
g