On Thu, Sep 11, 2014 at 4:24 PM, Steven G. Johnson <[email protected]> wrote:
> I really think that embedding documentation in comments is a mistake. > Documentation needs to be a part of the language, included in a > semantically meaningful way, not an add-on that is semantically meaningless > (comments). Either the documentation affects the meaning of the code or it doesn't. Type annotations give us a lot of functional documentation, with the advantage that it can't be out of sync with the code since it *is* the code. I'm in favor of having as much of this kind of "documentation" as possible. There will always, however, be more documentation that doesn't affect the behavior of the code. I'm not even sure what it means for that kind of documentation to be "semantically meaningful" – you mean that it has a specified format means something? I'm not sure why that has anything to do with whether this is in comments or not. How is a string that you parse and associate with a function more or less meaningful than a comment that you parse and associate with a function? To me the only difference is that I really don't want to write @doc """ commentary """ function ... whereas I already write things along the lines of # commentary function ... all the time. All the extra syntax makes this kind of documentation feel heavy and awkward instead of light and natural. In my experience, heavy, awkward things tend not to get used while light natural things tend to get used.
