> 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.
Here my modified suggestion for in-code documentation: https://gist.github.com/mauro3/3fe9c7fd16177dafe90a A few comments: - maybe a doc"..." string-macro/string-label could be good? To make it clear that this is documentation; to raise errors if there is nothing to associate the doc with? But maybe it's just clutter. - as I said, I prefer the doc inside a code-block (matlab/python style). To counter Stefan's arguments against this: the function/method declaration serves as the title (thus avoiding repetition), doc does not get lost easily when copy-pasting or refactoring, and (at least for modules) the scope of the doc-string should probably inside the module and not outside(?). (but either way is fine as long as we get it!) - not so sure about one-liners (functions, variables, abstract types,...). I think for them it would be even more handy to have a way to make sure documentation and declaration stay together. Maybe documentation up-front, a colon as glue and no newline allowed inbetween? - for abstract type it might be nice to allow an `end` to put the documentation inside the code-block. - if pre-code-block doc is adopted, then maybe a `:` like in above point could be nice too?
