Docile.jl author here, When I began writing it had some Steven's ideas in mind from one of the earlier discussion here (or GitHub issues list perhaps).
I had initially though of following go's use of comments above code objects to document them, but that doesn't allow for interpolating data from the module into the docstrings, which I believe Stefan had suggested at some point. Doing this allows you to programmatically generate docstrings such as when generating functions using `for` and `@eval` loops. You wouldn't be able to do this with comment in their current form and I'd think it wise to just leave comment as they are. I'd be very much in favour of a `doc` keyword rather than the current macro I'm using, but it's got me surprisingly far. Docile is, for the most part, self-documenting. `@doc` itself can't be documented using `@doc` unfortunately, perhaps there's some way around that. Spencer Lyon mentioned recently his interest in using it for one of his own packages. -- Mike
