rewritte old proposal api documentation to markdown

The angle brackets get swallowed in the HTML rendering. Use a backslash `\<` or `list(string)` for now and we will rubify it for YARD in the code.