Make sure that that every function in Phobos has an example: std.{algorithm,array,ascii,base64} #5581

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

@@ -120,7 +120,7 @@ exception_check="-std.concurrency,-std.net.curl,-std.parallelism,-std.range,-std
 ; Checks for poor placement of function attributes
 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

@@ -588,6 +595,7 @@ if (isDynamicArray!T && allSatisfy!(isIntegral, I))
    return arrayAllocImpl!(true, T, ST)(sizes);
 }

+///
 @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 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 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 requested 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 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

wilzbach added this to In progress in Public examples via automation Mar 20, 2018

JackStouffer moved this from In progress to Done in Public examples Mar 20, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make sure that that every function in Phobos has an example: std.{algorithm,array,ascii,base64} #5581

Make sure that that every function in Phobos has an example: std.{algorithm,array,ascii,base64} #5581

wilzbach commented Jul 8, 2017

dlang-bot commented Jul 8, 2017

MetaLang Jul 9, 2017 •

edited

wilzbach Jul 9, 2017

MetaLang Jul 9, 2017

MetaLang left a comment

JackStouffer Jul 9, 2017

JackStouffer Jul 9, 2017

JackStouffer Jul 9, 2017

JackStouffer Jul 9, 2017

wilzbach commented Jul 10, 2017

trikko Jul 21, 2017

wilzbach Jul 21, 2017

Make sure that that every function in Phobos has an example: std.{algorithm,array,ascii,base64} #5581

Make sure that that every function in Phobos has an example: std.{algorithm,array,ascii,base64} #5581

Conversation

wilzbach commented Jul 8, 2017

dlang-bot commented Jul 8, 2017

Bugzilla references

MetaLang Jul 9, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MetaLang left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wilzbach commented Jul 10, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MetaLang Jul 9, 2017 •

edited