I've been wanting (and, off and on, building) a system for tying documentation to supporting tests. On the one hand, it should serve as citations, making sure I don't make claims I can't hold up. On the other, it should help avoid the docs drifting out of sync with the code without undue cognitive overhead - telling me what I need to consider changing when the code changes.
One option would be to start with a spec and gradually add citations, doing TDD along the way for a sort of Documentation Driven Development, although I've no particular confidence that's actually a sweet spot.
doctest is a move in this direction, but only really makes sense for code you wish to surface as examples. Cucumber is also obviously related, but - so far as I understand - isn't really suitable for producing arbitrary documentation. Types are (amongst other things) another form of machine checked documentation, but the audience (and, usually, expressiveness) is naturally limited.
One option would be to start with a spec and gradually add citations, doing TDD along the way for a sort of Documentation Driven Development, although I've no particular confidence that's actually a sweet spot.
doctest is a move in this direction, but only really makes sense for code you wish to surface as examples. Cucumber is also obviously related, but - so far as I understand - isn't really suitable for producing arbitrary documentation. Types are (amongst other things) another form of machine checked documentation, but the audience (and, usually, expressiveness) is naturally limited.