> > I don't have a strong opinion on this topic, but I really don't understand > why this is better than using directly: > > @doc "This is a doc string: 1 + 2 = $(1+2)" > > What is lost when using a string compared to comments? >
The primary difference to me is the ease of expansion that comes along with comments. Ie, if there is already one line of comments, I just hit newline in my editor, and it automatically adds a new comment leader and I can add an additional thought to the comment. Whereas with strings and markup, I have to go and tidy up the ending quotations. But if we're proposing modifying the parser anyways, then we could get the best of both worlds with a* doc* keyword that is line terminated or block terminated just like the let keyword: doc begin lots of documentation, blah blah end also one lined: doc Foo is a function with .... and with optional arguments for specifying documentation type: doc rst Using some restructuredtext here.
