On Fri, Mar 2, 2012 at 1:27 PM, Mike Meyer <mwm@mired.org> wrote:
So the question is - why isn't dealing with this the responsibility of the test writer? Yeah, it's not quite the spirit of documentation to turn a dictionary into a sorted list in the output, but neither is littering the documentation with +LITERAL_EVAL and the like.
Currently the test-writer is not empowered to exercise this responsibility most effectively. Earlier, an example was presented that one should write
d = make_dict(...) d == {'a': 42, 'b': 23, 'c': None} True
rather than the implied
d = make_dict(...) {'a': 42, 'b': 23, 'c': None}
Using the former is certainly necessary today, but it's far from ideal. The documentor is stuck either writing the documentation clearly (the latter case) or testably (the former). The hope is to find a way to let people more easily write documentation that is both clear and testable. One thing that covers some--but far from all--cases is to ast.literal_eval or eval the output, since very often that output line is a repr of a Python expression. To be reasonable, this might require a directive in both cases and certainly requires one in the latter case. Though there are still tons of situations this cannot cover, it would allow people writing documentation to avoid ugly constructs like the first code snippet in a not-tiny set of cases. As for littering your code with "+doctest BLAH_BLAH", I don't think this is all that harmful. It allows the documentation writer get features she wants and will not display to the user in the processed documentation. There are already directives like this today and though ugly, they are conventional. Mike