If a docstring fails assertion checks, output the offending docstring…

[vsajip]

… to help the user pinpoint the problem.

[mhils]

Do you have an example where this is relevant?

[vsajip]

I had an extra newline after Args: in a docstring and it failed the assertion "not starting with '\n'", but that didn't tell me which docstring it was. I had to change the source to catch the AssertionError to see the location of my error.

[mhils]

Thanks for clarifying! We don't want to crash in this case, we want to handle the whitespace gracefully. #459 fixes the underlying issue.

[vsajip]

Yes, agreed, of course - this is better. I didn't know how strict you wanted to be, and didn't want to presume you'd be OK with relaxing the condition.

[mhils]

All good, thanks. :) As a general rule, docstring conversion should never crash.

[vsajip]

What about the "\t" not in contents assertion, though? Couldn't a stray tab char in the source cause a crash?

[mhils]

Yes, that's a very fair point. We probably just want to remove that line? Do you want to send a PR? :)

[vsajip]

Also, the assertions are there to catch unexpected conditions (unconsidered corner case, or regression) - if they are ever going to fire, the error message may as well be more informative than at present.

[mhils]

Fair point - let's pipe out the docstring in question, but let's not allocate an unneeded error message. :)

[vsajip]

Sure, that's fine by me 😄