Make sure that every function in Phobos has a public example
Seb via Digitalmars-d
digitalmars-d at puremagic.com
Thu Jul 20 05:40:15 PDT 2017
Examples are a great way to explore functions on Phobos. They
provide an intuitive, playful alternative to reading the docs -
especially now that they are
interactive [1].
They are so important that people even report bugs if they don't
exist [2].
However, Phobos still doesn't come with a (public) unittest for
every function.
So, do you have ten minutes to improve Phobos and "unittestify" a
module?
This doesn't require in-depth knowledge of Phobos and is a great
way to get started with Phobos's codebase.
The workflow is rather easy:
1) Pick a module from the blacklist [3]
2) Remove it from the blacklist
3) Run DScanner: `make -f posix.mak dscanner`
4) Add public unittest to the missing places (A public unittest
is marked with a /// comment)
5) Run the test of the module to see if your new examples are
correct:
With the newest compiler: dmd -unittest -run std/foo.d
Otherwise: make -f posix.mak std/foo.test
6) Create a branch, commit your work & send a pull request
7) GOTO easy;
I went ahead and set a good example:
https://github.com/dlang/phobos/pull/5581
Of course, each module can be a separate PR as well.
Let me know if you have questions or run into troubles.
For example, on Ubuntu 16.10 and Arch Linux, you need to use
PIC=1 (e.g. make -f posix.mak dscanner PIC=1) to compile the
examples (at least until [4] is merged).
Current blacklist [3]
---------------------
has_public_example="-etc.c.curl,-etc.c.sqlite3,-etc.c.zlib,-std.bitmanip,-std.complex,-std.concurrency,-std.container.array,-std.container.dlist,-std.container.rbtree,-std.container.slist,-std.conv,-std.csv,-std.datetime,-std.datetime.date,-std.datetime.interval,-std.datetime.stopwatch,-std.datetime.systime,-std.datetime.timezone,-std.demangle,-std.digest,-std.digest.hmac,-std.digest.murmurhash,-std.digest.sha,-std.encoding,-std.exception,-std.experimental.allocator,-std.experimental.allocator.building_blocks.allocator_list,-std.experimental.allocator.building_blocks.bitmapped_block,-std.experimental.allocator.building_blocks.fallback_allocator,-std.experimental.allocator.building_blocks.free_list,-std.experimental.allocator.building_blocks.free_tree,-std.experimental.allocator.building_blocks.null_allocator,-std.experimental.allocator.building_blocks.stats_collector,-std.experimental.allocator.common,-std.experimental.allocator.mmap_allocator,-std.experimental.allocator.typed,-std.experimental.checkedint,-std.experimental.logger.core,-std.experimental.logger.filelogger,-std.experimental.logger.multilogger,-std.experimental.typecons,-std.file,-std.format,-std.getopt,-std.internal.math.biguintcore,-std.internal.math.biguintnoasm,-std.internal.math.errorfunction,-std.internal.math.gammafunction,-std.internal.scopebuffer,-std.internal.test.dummyrange,-std.json,-std.math,-std.mathspecial,-std.mmfile,-std.net.curl,-std.net.isemail,-std.numeric,-std.outbuffer,-std.parallelism,-std.path,-std.process,-std.random,-std.range,-std.range.interfaces,-std.range.primitives,-std.regex,-std.regex.internal.ir,-std.socket,-std.stdio,-std.string,-std.traits,-std.typecons,-std.uni,-std.uri,-std.utf,-std.uuid,-std.variant,-std.xml,-std.zip,-std.zlib"
[1]
https://dlang.org/blog/2017/03/08/editable-and-runnable-doc-examples-on-dlang-org
[2] https://issues.dlang.org/show_bug.cgi?id=17670
[3] https://github.com/dlang/phobos/blob/master/.dscanner.ini#L123
[4] https://github.com/dlang/phobos/pull/5586
More information about the Digitalmars-d
mailing list