After some discussion these are the two (and a half) proposals. Each has some pros and cons which will be assest later.
1. @doc
The original proposal. Based on the existing @propTypes idea and formatting
1.5 @doc rearranged
Essentially the same as the original proposal. But now the types and summaries are next the properties instead of being grouped together. (Some syntax highlighting is added as well)
2. Comments
The other proposal is to use comments as a semantic way to add documentation.
(This has complete syntax highlighting applied)
Notes
Beware that full syntax highlighting and completion will be added to the final proposal regardless which will be chosen. The highlighting in the examples is just to get some feel for it.
Also keep in mind that color and styling is fully depending on the theme:
