Generally the idea is:
- use Prism to parse the file into AST + Comments
- transform each comment block into plain RDoc (instead of RDoc in a
comment)
- use RDoc's ToMarkdown class to get a Markdown representation of the
comment
- transform the Markdown representation back into a comment
- write a new file, skipping the lines that were previously RDoc
comments and instead inserting the new Markdown comments
A little extra work has to be down for metaprogrammed documentation
because ToMarkdown turns RDoc directives into H1s. So for these cases,
the directive is first split off the top before doing the ToMarkdown
transformation and then added back afterwards.
