On Thursday, August 28, 2014 4:53:59 PM UTC-4, Stefan Karpinski wrote: > > We don't need flexible documentation – we need one simple documentation > system that works. >
I don't think that simplicity needs to come at the price of flexibility. 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.) 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 (e.g. how do you associate the docstring comment with a constant? with a Function as opposed to a specific method) etc. 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.
