Vote?

[Jonathan M Davis]

On Friday, November 18, 2011 05:01:22 Jesse Phillips wrote:
> On Thu, 17 Nov 2011 18:26:08 -0800, Jonathan M Davis wrote:
> > dsimcha did forget to put an end date on the voting for std.csv, but it
> > started on Saturday, and votes have typically been about a week long, so
> > the voting will presumably close sometime Saturday (Sunday at the
> > latest), and yet only _two_ people have voted thus far. I don't know if
> > we can even reasonably count that as passing if that's all who vote.
> > 
> > So, please don't forget to vote if you intend to.
> > 
> > - Jonathan M Davis
> 
> Thank you, and on the description of what csvReader returns I'm wanting
> something like:
> 
> Returns:
>       An input range as defined by $(XREF range, isInputRange). When $(D
> Contents) is a struct or associative array the range is of that type,
> otherwise it is a range of ranges of that type.
> 
> And the questions are, is "range is of that type" good?
> 
> How can you express that you have a range of ranges cleanly? This is the
> hardest one to express.

I'd probably do something like

Returns:
    An input range of rows where if ($D Contents) is a struct or assocative 
array, each row is a $(D Contents), and if not, each row is an input range of 
$(D Contents).

Of course, that would sound better if Contents didn't have have an s on the 
end (type names don't usually have an s on the end, and it's weird when they 
do, though I don't think that a good name in this case is necessarily 
obvious). Entry? Of course, then you get the weirdness of "an input range of 
($D Entry)s."

The large difference between returning a range of structs or AAs vs returning a 
range of ranges of whatever type the entries are makes it seem like they 
really should be documented as two different overloads, but since the difference 
is in the template constraints rather than in the function signature, I don't 
see a good way to do that. It _does_ make the documentation much harder to 
write or understand the way it is though - and not in a way that explicitly 
documenting the return type would really help. It's the signatures that are 
the issue, and the language doesn't provide a good, obvious way to deal with 
that, given that it's the template constraints that differ.

By the way, if csvReader doesn't support classes (and it doesn't appear to), 
that should be mentioned in the docs - especially if you're talking about 
structs, AAs, and everything that isn't a struct or AA, which appears to be 
what's happening at the moment.

- Jonathan M Davis