Make sure that that every function in Phobos has an example: std.{algorithm,array,ascii,base64} by wilzbach · Pull Request #5581 · dlang/phobos

wilzbach · 2017-07-08T23:07:27Z

Make sure that that every function in Phobos has an example

The check has_public_example has been there for quite some time, so I thought I go ahead and set a good example.

@ everyone there are many checks that would be worthwhile to reduce one module at a time.
Apart from has_public_example, there's properly_documented_public_functions (checks that every function has "Params" + "Returns", part Walter's calls to action: 2016, 2015, could_be_immutable_check or find TODO checks yourself in the .dscanner.ini.

dlang-bot · 2017-07-08T23:07:28Z

Thanks for your pull request, @wilzbach!

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

MetaLang · 2017-07-09T20:04:03Z

.dscanner.ini

 function_attribute_check="-std.algorithm.iteration,-std.concurrency,-std.conv,-std.datetime.interval,-std.exception,-std.functional,-std.net.curl,-std.numeric,-std.parallelism,-std.random,-std.range,-std.range.primitives,-std.socket,-std.traits,-std.typecons,-std.uni"
 ; Check for public declarations without a documented unittest
-has_public_example="-etc.c.curl,-etc.c.sqlite3,-etc.c.zlib,-std.algorithm.comparison,-std.algorithm.mutation,-std.array,-std.ascii,-std.base64,-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.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"
+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.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"


I wish we could generate this list ~~manually~~ automatically.

FYI the list was generated automatically: #5501 - just reducing it isn't automated :/

Whoops, I just realized I wrote manually by mistake. At least the generating part works so we're not too bad off.

MetaLang

LGTM

JackStouffer · 2017-07-09T22:08:16Z

std/array.d

+unittest
+{
+    auto w = appender!string;
+    // pre-allocate at least 10 elements (this avoids costly reallocations)


nitpick: pre-allocate at least 10 elements -> pre-allocate space for at least 10 elements

JackStouffer · 2017-07-09T22:10:12Z

std/array.d

+///
+@safe unittest
+{
+    assert("Hello D".array == "Hello D"d);


Just in case people don't know who are reading this, I would add

static assert(isRandomAccessRange!string == false);

here, and then

static assert(isRandomAccessRange!dstring == true);

at the end

JackStouffer · 2017-07-09T22:11:01Z

std/array.d

 }

+///
 @safe pure nothrow unittest


This example is rather confusing, and seems to be testing edge cases. Can something more simple be used here?

JackStouffer · 2017-07-09T22:12:49Z

std/base64.d

+
+    // pre-defined: alias Base64 = Base64Impl!('+', '/');
+    ubyte[] emptyArr;
+    assert(Base64.encode(emptyArr)                == "");


Let's avoid aligned equals signs. See the Class/Struct Field Declarations section here https://dlang.org/dstyle.html

wilzbach · 2017-07-10T00:31:17Z

Let's avoid aligned equals signs.

This was done as it was the existing style, but fair enough ;-)

trikko · 2017-07-21T07:24:57Z

std/algorithm/mutation.d

+@safe unittest
+{
+    import std.stdio;
+    import std.algorithm.sorting : partition;


Why do you import "partition"?

No particular reason except for copy/pasting from the test below :/

has_public_example: std.algorithm.comparison

334642b

wilzbach added the Severity:Documentation label Jul 8, 2017

wilzbach force-pushed the has_public_example branch 2 times, most recently from 6f563e9 to a7446db Compare July 9, 2017 00:28

has_public_example: std.algorithm.mutation

8180178

wilzbach force-pushed the has_public_example branch from a7446db to f164ee4 Compare July 9, 2017 00:32

wilzbach added the Review:Trivial typos, formatting, comments label Jul 9, 2017

MetaLang reviewed Jul 9, 2017

View reviewed changes

MetaLang approved these changes Jul 9, 2017

View reviewed changes

JackStouffer suggested changes Jul 9, 2017

View reviewed changes

wilzbach added 2 commits July 10, 2017 02:28

has_public_example: std.array

b6512b9

has_public_example: std.ascii

cc80b57

wilzbach force-pushed the has_public_example branch from f164ee4 to 0fb288f Compare July 10, 2017 00:29

wilzbach mentioned this pull request Jul 10, 2017

Enable section links to the DStyle dlang/dlang.org#1813

Merged

wilzbach force-pushed the has_public_example branch from 0fb288f to 54c47a7 Compare July 10, 2017 00:58

has_public_example: std.base64

54c47a7

JackStouffer approved these changes Jul 10, 2017

View reviewed changes

JackStouffer added the Merge:auto-merge label Jul 10, 2017

dlang-bot merged commit 568210f into dlang:master Jul 10, 2017

wilzbach deleted the has_public_example branch July 20, 2017 11:40

trikko reviewed Jul 21, 2017

View reviewed changes

Uh oh!

Conversation

wilzbach commented Jul 8, 2017

Uh oh!

dlang-bot commented Jul 8, 2017

Bugzilla references

Uh oh!

MetaLang Jul 9, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MetaLang left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wilzbach commented Jul 10, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Comments

MetaLang Jul 9, 2017 •

edited

Loading