restructure state api doc
minor text changes and reorg