From 9118661ca23c727cd8cd1f8505a3f5cf9aa8342a Mon Sep 17 00:00:00 2001 From: Nick Treleaven Date: Mon, 9 Jan 2017 12:10:50 +0000 Subject: [PATCH 1/2] Tweak ScopeBuffer docs * Fix ddoc for commented out `this(this)` showing in `put`'s docs. * Fix missing ddoc for `put(CT[])` due to private `CT`. * Use documented unittest for scopeBuffer instead of inline code. --- std/internal/scopebuffer.d | 61 ++++++++++++++++++-------------------- 1 file changed, 29 insertions(+), 32 deletions(-) diff --git a/std/internal/scopebuffer.d b/std/internal/scopebuffer.d index f92856477bd..7ee1288e591 100644 --- a/std/internal/scopebuffer.d +++ b/std/internal/scopebuffer.d @@ -15,18 +15,18 @@ private import std.traits; /************************************** * ScopeBuffer encapsulates using a local array as a temporary buffer. - * It is initialized with the local array that should be large enough for - * most uses. If the need exceeds the size, ScopeBuffer will resize it - * using malloc() and friends. + * It is initialized with a local array that should be large enough for + * most uses. If the need exceeds that size, ScopeBuffer will reallocate + * the data using its `realloc` function. * - * ScopeBuffer cannot contain more than (uint.max-16)/2 elements. + * ScopeBuffer cannot contain more than `(uint.max-16)/2` elements. * - * ScopeBuffer is an OutputRange. + * ScopeBuffer is an Output Range. * - * Since ScopeBuffer potentially stores elements of type T in malloc'd memory, + * Since ScopeBuffer may store elements of type `T` in `malloc`'d memory, * those elements are not scanned when the GC collects. This can cause - * memory corruption. Do not use ScopeBuffer when elements of type T point - * to the GC heap. + * memory corruption. Do not use ScopeBuffer when elements of type `T` point + * to the GC heap, except when a `realloc` function is provided which supports this. * * Example: --- @@ -80,7 +80,7 @@ string cat(string s1, string s2) * $(D scope(exit) textbuf.free();) for proper cleanup, and do not refer to a ScopeBuffer * instance's contents after $(D ScopeBuffer.free()) has been called. * - * The realloc parameter defaults to C's realloc(). Another can be supplied to override it. + * The `realloc` parameter defaults to C's `realloc()`. Another can be supplied to override it. * * ScopeBuffer instances may be copied, as in: --- @@ -88,7 +88,7 @@ textbuf = doSomething(textbuf, args); --- * which can be very efficent, but these must be regarded as a move rather than a copy. * Additionally, the code between passing and returning the instance must not throw - * exceptions, otherwise when ScopeBuffer.free() is called, memory may get corrupted. + * exceptions, otherwise when `ScopeBuffer.free()` is called, memory may get corrupted. */ @system @@ -111,9 +111,10 @@ struct ScopeBuffer(T, alias realloc = /*core.stdc.stdlib*/.realloc) * ubyte[10] tmpbuf = void; * auto sbuf = ScopeBuffer!ubyte(tmpbuf); * --- - * If buf was created by the same realloc passed as a parameter - * to ScopeBuffer, then the contents of ScopeBuffer can be extracted without needing - * to copy them, and ScopeBuffer.free() will not need to be called. + * Note: + * If buf was created by the same `realloc` passed as a parameter + * to `ScopeBuffer`, then the contents of `ScopeBuffer` can be extracted without needing + * to copy them, and `ScopeBuffer.free()` will not need to be called. */ this(T[] buf) in @@ -135,7 +136,7 @@ struct ScopeBuffer(T, alias realloc = /*core.stdc.stdlib*/.realloc) /************************** * Releases any memory used. - * This will invalidate any references returned by the [] operator. + * This will invalidate any references returned by the `[]` operator. * A destructor is not used, because that would make it not POD * (Plain Old Data) and it could not be placed in registers. */ @@ -152,11 +153,12 @@ struct ScopeBuffer(T, alias realloc = /*core.stdc.stdlib*/.realloc) /**************************** * Copying of ScopeBuffer is not allowed. */ - //@disable this(this); + version(None) + @disable this(this); /************************ * Append element c to the buffer. - * This member function makes ScopeBuffer an OutputRange. + * This member function makes `ScopeBuffer` an Output Range. */ void put(T c) { @@ -178,7 +180,7 @@ struct ScopeBuffer(T, alias realloc = /*core.stdc.stdlib*/.realloc) * If $(D const(T)) can be converted to $(D T), then put will accept * $(D const(T)[]) as input. It will accept a $(D T[]) otherwise. */ - private alias CT = Select!(is(const(T) : T), const(T), T); + package alias CT = Select!(is(const(T) : T), const(T), T); /// ditto void put(CT[] s) { @@ -195,10 +197,10 @@ struct ScopeBuffer(T, alias realloc = /*core.stdc.stdlib*/.realloc) } /****** - * Retrieve a slice into the result. * Returns: - * A slice into the temporary buffer that is only - * valid until the next put() or ScopeBuffer goes out of scope. + * A slice into the temporary buffer. + * Warning: + * The result is only valid until the next `put()` or `ScopeBuffer` goes out of scope. */ @system inout(T)[] opSlice(size_t lower, size_t upper) inout in @@ -221,7 +223,7 @@ struct ScopeBuffer(T, alias realloc = /*core.stdc.stdlib*/.realloc) /******* * Returns: - * the element at index i. + * The element at index i. */ ref inout(T) opIndex(size_t i) inout { @@ -231,7 +233,7 @@ struct ScopeBuffer(T, alias realloc = /*core.stdc.stdlib*/.realloc) /*** * Returns: - * the number of elements in the ScopeBuffer + * The number of elements in the `ScopeBuffer`. */ @property size_t length() const { @@ -240,7 +242,7 @@ struct ScopeBuffer(T, alias realloc = /*core.stdc.stdlib*/.realloc) /*** * Used to shrink the length of the buffer, - * typically to 0 so the buffer can be reused. + * typically to `0` so the buffer can be reused. * Cannot be used to extend the length of the buffer. */ @property void length(size_t i) @@ -367,18 +369,12 @@ unittest } /********************************* - * This is a slightly simpler way to create a ScopeBuffer instance - * that uses type deduction. + * Creates a `ScopeBuffer` instance using type deduction - see + * $(LREF .ScopeBuffer.this) for details. * Params: * tmpbuf = the initial buffer to use * Returns: - * an instance of ScopeBuffer - * Example: ---- -ubyte[10] tmpbuf = void; -auto sb = scopeBuffer(tmpbuf); -scope(exit) sp.free(); ---- + * An instance of `ScopeBuffer`. */ auto scopeBuffer(T)(T[] tmpbuf) @@ -386,6 +382,7 @@ auto scopeBuffer(T)(T[] tmpbuf) return ScopeBuffer!T(tmpbuf); } +/// unittest { ubyte[10] tmpbuf = void; From c32a2f4eda79c252c9b8ea8e88343740a384d45c Mon Sep 17 00:00:00 2001 From: Nick Treleaven Date: Tue, 10 Jan 2017 12:13:49 +0000 Subject: [PATCH 2/2] Remove old code - copying is allowed --- std/internal/scopebuffer.d | 6 ------ 1 file changed, 6 deletions(-) diff --git a/std/internal/scopebuffer.d b/std/internal/scopebuffer.d index 7ee1288e591..f4d019f4963 100644 --- a/std/internal/scopebuffer.d +++ b/std/internal/scopebuffer.d @@ -150,12 +150,6 @@ struct ScopeBuffer(T, alias realloc = /*core.stdc.stdlib*/.realloc) used = 0; } - /**************************** - * Copying of ScopeBuffer is not allowed. - */ - version(None) - @disable this(this); - /************************ * Append element c to the buffer. * This member function makes `ScopeBuffer` an Output Range.