get rid of long docstring
add a 'base' param to flags func
rename stuff; add an OK docstring; add better comments