make phpdoc more specific

was confused while reviewing #33 - i think this is documenting correctly how things work. but please review @ddeboer