<p dir="auto">by <strong>fuzxxl</strong>:</p>
<pre class="notranslate">Right now, the package io specifies the Seeker with its sole method Seek(). The
whence-parameter of Seek() is specified to accept one of the constants 1 to 3 with
certain semantics.

io does not provide symbolic constants for the whence-parameter, even there should
clearly be a set for clarity. os provides such constants though:

const (
        SEEK_SET int = 0 // seek relative to the origin of the file
        SEEK_CUR int = 1 // seek relative to the current offset
        SEEK_END int = 2 // seek relative to the end
)

I think these constants are at the wrong place since if you want to use a generic
Seeker, you have to import os, a module with a concrete Seeker implementation, if you
want to use symbolic constants for the whence parameter. This gives people who have a
glance at your code the wrong idea that the source code they are looking at actually
communicates with the operating system which it might not do.

To fix this issue, I suggest duplicating the constants SEEK_SET, SEEK_CUR and SEEK_END
into the io module and suggesting people to use the symbolic constants from there
instead from os, as they semantically belong to io IMHO.

This change would only affect backwards-compatibility if somebody declared SEEK_SET,
SEEK_CUR and SEEK_END in their own source code while importing io without a qualifier,
but this is explicitly allowed by the compatibility rules.</pre>
<p dir="auto">In <a href="https://godoc.org/golang.org/x/net/context#Context" rel="nofollow">https://godoc.org/golang.org/x/net/context#Context</a>, there are two possible readings for the documentation of Err:</p>
<ol dir="auto">
<li>Err() must return nil before Done() isn't closed, and atomically switch to returning some non-nil error when Done() IS closed</li>
<li>Err() is undefined before Done() is closed, and the only valid use for Err() is after blocking on Done()</li>
</ol>
<p dir="auto">Looking at the implementation, I suspect that 1 is the correct interpretation. I would propose that the documentation on this function be amended to read:</p>
<div class="highlight highlight-source-go notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="    // Err returns a non-nil error value after Done is closed.  Err returns
    // Canceled if the context was canceled or DeadlineExceeded if the
    // context's deadline passed.  If Done is not yet closed, Err must return nil.
    // No other values for Err are defined. After Done is closed, successive
    // calls to Err return the same value.
    Err() error"><pre class="notranslate">    <span class="pl-c">// Err returns a non-nil error value after Done is closed.  Err returns</span>
    <span class="pl-c">// Canceled if the context was canceled or DeadlineExceeded if the</span>
    <span class="pl-c">// context's deadline passed.  If Done is not yet closed, Err must return nil.</span>
    <span class="pl-c">// No other values for Err are defined. After Done is closed, successive</span>
    <span class="pl-c">// calls to Err return the same value.</span>
    <span class="pl-en">Err</span>() <span class="pl-s1">error</span></pre></div>
<p dir="auto">Note the added "If Done is not yet closed, Err must return nil." sentence.</p>