update docstring and WIP comments
update docstring and WIP comments

saimn/astropy,mhvk/astropy,saimn/astropy,StuartLittlefair/astropy,StuartLittlefair/astropy,larrybradley/astropy,pllim/astropy,pllim/astropy,lpsinger/astropy,pllim/astropy,mhvk/astropy,saimn/astropy,saimn/astropy,mhvk/astropy,astropy/astropy,larrybradley/astropy,StuartLittlefair/astropy,pllim/astropy,pllim/astropy,lpsinger/astropy,StuartLittlefair/astropy,astropy/astropy,astropy/astropy,saimn/astropy,lpsinger/astropy,larrybradley/astropy,astropy/astropy,astropy/astropy,larrybradley/astropy,mhvk/astropy,StuartLittlefair/astropy,larrybradley/astropy,mhvk/astropy,lpsinger/astropy,lpsinger/astropy