Pre-RFC: Documentation Test Names

I was working on a project with a bunch of documentation tests, and found the test runner's output to be somewhat unhelpful. In particular, when a doctest in a module with a bunch of other doctests failed, I had to go to the line number to see what the test did, or try to identify the test by the error message. Additionally, it was hard to see which doctests were running.

So, I wrote a simple RFC that proposes the ability to add metadata of the form name=IDENT to documentation test code block info strings. Markdown supports space-separated multi-word code block info strings, so this isn't an extension of markdown.

I'd be interested to hear if you think this is a good idea, or not, and any improvements/suggestions you might have.

You can read the RFC here.

2 Likes

This sounds really nice, I would use this if it existed!

I would consider loosening the uniqueness requirements - this is effectively just a label, for printing and the examples given still print the line number, so it feels like more hassle (both for the code writer, and for the implementation to process the examples) than it's worth...

1 Like

Sweet!

I was thinking that requiring that labels be unique rust identifiers might the doctests code generator, by allowing labels to be used as the generated function names. However, I can see how that would be annoying.

I removed the identifier and uniqueness requirements, and moved them to the rationale and alternatives section, with some commentary. If, during the RFC process, someone with more familiarity with the doctest code generation thinks that unique rust identifiers would be beneficial for code generation, then those restrictions can be de-demoted back to the RFC body.

1 Like

How would this interact with other annotations for the doctest, like compile_fail? I think there's some syntax for commas currently, would it reuse that?

1 Like

I didn't know that there was the ability to separate items in an info string with commas! I'll update the RFC to use that.

1 Like