On Friday, 29 August 2014 12:59:21 UTC+2, Steven G. Johnson wrote: > > And if you sacrifice flexibility, you might easily end up with something > that works for now, but is an annoyance in a few years. (It is really hard > to add more structured information into Python docstrings, for example.) >
If you include programmability and flexibility when it's not needed, you invite abuse. *Especially* if the target audience isn't primarily trained as programmers. We could choose to have different multiline comments count as different documentation blocks, and allow declaring a mimetype per comment block: #= no mimetype, defaults to markdown =# #= image/svg+xml [svg data, or link to source] =# function f() That should give enough flexibility and room for growth, I would say. I think putting documentation in something that is not syntactically > meaningful -- comments -- will get more and more annoying, because you'll > end up inventing more and more ad-hoc rules for how to associate which > documentation with which object First, if we design a proper convention for comments to have them work as a form of documentation, then don't they by definition become syntactically meaningful? It's a bit of a false premise. Also, the association works the same way it works for code: by placing the right tokens next to each other, following a certain standard. > e.g. how do you associate the docstring comment with a constant? > Is the constant publically visible? Then it's probably top level, so a comment directly above it works. That's what Go does. > with a Function as opposed to a specific method > Ok, I admit this one is a bit trickier. But if we still have the store-in-a-dictionary approach you proposed (which as far as I can see does not conflict with comment-based documentation) one can directly add documentation to the dictionary in the same way one would for any dictionary. > Not to mention that the documentation system will have to decide which > comments are docstrings and which comments are just internal comments by > programmers who didn't intend for the comment to be an end-user doc. > That is essentially arguing using a convention is a bad idea because some people won't be aware of it and accidentally will show comments not relevant to the outside world, yet I have seen no examples of this confusion in the Go community.
