On Wed, Jun 11, 2014 at 7:17 PM, Michael Hatherly <michaelhathe...@gmail.com > wrote:
> Regarding in-code vs separate docs: I was playing around with some ideas > this > afternoon related to that. Seems easy enough to support both kinds. I was > using multiline comments above method definitions. I'm not sure whether > having the doc string/comment above or below is better, but generally they > seem to appear before the code that I've looked at. Open to suggestions on > this, since I prefer to just document separately and so have no preference. > Supporting both above and below might lead to more confusion than it's > worth. > My inclination is to associate multiline strings in void context with the things that comes after them. For example, like this: https://gist.github.com/StefanKarpinski/e1c599de7b8a42129107 This allows comments to continue to just be comments, and allows globals to be spliced into docstrings with interpolation. By having the documentation in global context, you avoid the problem of what to do with local variables that may be interpolated into docstrings, and how to distinguish between a string that is being returned from a single-expression function and a docstring in a function with an empty body (this could be resolved with some rule, but it seems better to simply not have the issue in the first place.
