At 03:35 PM 9/26/2005 -0700, Micah Elliott wrote:
Please read/comment/vote. This circulated as a pre-PEP proposal submitted to c.l.py on August 10, but has changed quite a bit since then. I'm reposting this since it is now "Open (under consideration)" at http://www.python.org/peps/pep-0350.html.
This seems a little weird to me. On the one hand, seems like a cool idea if you aren't using Eclipse or another IDE that tracks this stuff, but still need some kind of tracking system. But, if that is the case, the notation seems a little bit overkill, especially with respect to tracking who's responsible - i.e., just you. If you have a team that can agree to use the tools, I suppose it might be useful, but then I wonder, why not use something like Trac? Finally, I think there should be something besides just a comment to distinguish these things; like starting with a symbol (e.g. # !FIXME), so that that documentation extraction tools can distinguish code tags from other documentation that just happens to start with a CAPITALIZED word. Overall, I'm kind of -0.5. It seems like a spec in search of an application. The Motivation is sorely lacking - it reads like, "hey, it's optional and you can do stuff", where the stuff you can do is deferred to a later section, and is mostly stuff that could easily be done in other ways. For example, FIT-style acceptance test documents, or Python doctest files go a long way towards documenting stories in association with tests, and they don't require you to cram things into comments. (And because they're executable tests, they get kept up-to-date.) Tracking bugfixes with code history is handled nicely by tools like Trac. There are lots of Python documentation tools already. And so on. Really, it reads to me like you came up with the features to sell the format, instead of designing the format to implement specific features. My suggestion: implement some tools, use them for a while, and come back with more focused use cases to show why only this format can work, and why the Python core developers should therefore use it. I'm not saying that you can't have an informational PEP unless it should be used in the stdlib, mind you. Just pointing out that if you can't convince the core developers it's useful, I'm thinking you'll have a hard time convincing the community at large to actually use it. You need to actually have a better mousetrap to present before you ask people to move their cheese. :)