Encourage the creation of verifiable usage examples to help potential users form appropriate mental models.
This is an early stage project. Be sure to examine the fine print.
-
Within
commentblocks, put expressions / forms to be verified along with brief records of expected values:(comment (- 1 1) # => 0 )
Note the use of a single line comment and
⇒to express an expected return value.One might call the combination of the form and the comment with the expected value a "comment block test".
See Usage Writing Tips for more details.
-
Once some setup steps are followed, usage examples can be run by:
jpm test
Setting things up is mostly a matter of copying a single file.
Suppose there’s a project directory like:
.
├── my-src-dir
│ └── fun.janet
├── project.janet
└── test
└── test.janet
Copy the file
test/usages.janet
from this repository to the target project’s test subdirectory.
Alternatively, from the target project’s test subdirectory this might work:
curl -O https://gitlab.com/sogaiu/janet-usages/-/raw/master/test/usages.janet
Now it should look something like:
.
├── my-src-dir
│ └── fun.janet
├── project.janet
└── test
├── test.janet
└── usages.janet <-- copied this file into place
If jpm test is executed and there isn’t already a usages directory,
it will be created along with a sample.janet file:
.
├── my-src-dir
│ └── fun.janet
├── project.janet
├── test
│ ├── test.janet
│ └── usages.janet
└── usages <-- created this directory
└── sample.janet <-- created this file
sample.janet is just an example. Please feel free to modify it or
erase it after examining it.
See Details for additional information regarding the various files and directories.
To run the tests and get a report: jpm test
Add more usage examples by creating more comment block tests in files
that live in the usages directory.