The Eclipse Scala IDE (and Intellij Idea, too) has, together with a standard REPL CLI, an artifact named Worksheet, that works like a persistent REPL log: the whole file is compiled and executed at save time, and the results are in-lined as comments. It is a great tool for API exploration and design, and initial testing.
Is there any guideline if such a file belongs to the SCM?
I usually don't share those files, because they are often rough, limited in scope and not commented, being a way to test and try different ideas. Sometimes, however, a worksheet gains enough value and informative content to become valuable.
Should it be converted to a unit test or committed as is? do you find it an effective way to document and share the design or some example usage of a piece of code?