practicalli / practicalli/clojure
testing docstrings
Nobody has claimed this yet.
- Dominant language
- Makefile
- Stars
- 117
- Forks
- 36
- PR merge metrics
- No merged PRs in 30d
Description
Extend the cloure.test is macro to test that docstrings correctly describe what the function does (to investigate this - docs a little vauge)
https://github.com/liquidz/testdoc
why not to use test metadata? In that case you are not editing a string but normal clojure code
Because this can test that examples you provide in docstrings are correct (as well as regular tests, via metadata).
For the same reason that seancorfield/readme exists, to turn README files into tests, so you can verify that examples in your documentation are correct.
(although this testdoc may be a better solution, even for README files, depending on how it deals with non-test code etc)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the clojure.test macro behavior and the linked liquidz/testdoc project. Define how docstrings should be checked, including executable examples and regular metadata tests; done means the proposed extension can verify those examples without ambiguity.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- clojure
- Domain
- documentation, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100