This technique which has been coined ‘doctests’ nowadays sees wide usage in a number of other programming languages (c.f. Elixir, Rust and Python).
From first-hand experience with being tasked to write maintainable code in each of these languages, I would like to give this technique my glowing recommendation.
EDIT: it seems like there was already some prior discussion on this forum about this some 1.5 years back: Does PLDoc have a way to incorporate unit tests akin to Python's doctest? although I do not know in which way (if at all) PLdoc and SWI-Prolog’s documentation capabilities are related.