> From: Ka-Ping Yee [mailto:python-dev@zesty.ca] > > One can separate two issues here: > > 1. too much functionality (YAGNI) > 2. too many ways of expressing the same functionality (TMTOWTDI) >From my reading of the reST docs at various times, I've come to the conclusion that YAGNI doesn't apply - that each of the features exists because someone *did* need it (i.e. they had a real use case for it). I do feel that the explanations of some of the constructs are somewhat confusing. I think all constructs should include at least one (and preferably more) use cases in their explanations. Personally, I'm in favour of having the complete reST specification, but have well-defined conventions for usage of reST within specific applications. So a "docstring convention" document would specify what the structure of a docstring should (or must) include, how it is parsed, what interpreted text means, etc. Fairly comprehensive examples should be included. Unless you had very specific need you shouldn't go outside of the convention, but it should be available if you needed it for something which couldn't be expressed otherwise. If all you wanted to do was write docstrings, you would refer to the docstring convention document. If you wanted to write a PEP, you would refer to the PEP convention document. Because they use the same underlying syntax, knowning how to do one will help with learning how to do the other. One may normally use more (or different) constructs than the other, but there will be a lot of crossover. Tim Delaney
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4