rewritte old proposal api documentation to markdown

well, I remove it because it is very bad and quite confusing. Maybe I should add here mine one which is more correct.