Make Simple Things Hard to Figure out

[default0 via Digitalmars-d-learn]

Hi

So today I tried setting up vibe.d and see how that all works out.
Doing the initial setup was easy enough (dub is amazingly 
convenient!) and I had a "Hello World" server up and running in 
about 10 minutes. Sweet.
After that, I started looking into vibes URLRouter - also easy 
enough, documented good enough to get the gist of it without 
having to spend a long time doing anything.

After that, it all went downhill for me.
First off, I'm very new to D, I'm also very new to lots of the 
concepts D implements/exposes (low-level stuff, most the 
paradigms, etc). This is mostly a description of what I did to 
attempt solving my problems and how that did or did not work out. 
Maybe this can help guide decisions on what things to clarify and 
where.

The thing I was trying to do was dead simple: Receive a base64 
encoded text via a query parameter.
After digging around the HTTPRequest vibe exposes, I quickly 
found the query-dictionary, so to get my base64 encoded text, all 
I had to do was query["data"]. Easy, convenient.
To decode the base64 there is something in the std-lib. Awesome. 
So all I need to do is Base64URL.decode(query["data"]) and I'm 
done. Or so I thought. Naturally, the decode function returns a 
ubyte[], so I need to somehow decode the ubyte[] to a char[] 
(since I'm using a frontend-library that encodes base64 text as 
utf8).
My first instinct was to use google.
The first thing that came up was unsurprisingly std.utf.
After skimming through the functions I couldn't really make any 
function out that would accept a simple ubyte[] (or range of 
ubyte) and output a simple string or char[] (or range of chars). 
Disappointing. Maybe I missed something?
There is a decode function, but I couldn't quite figure out what 
it did or how I was supposed to use it, if it did what I wanted 
it to - no examples.

After that I moved on to std.string. It only had one function 
that seemed somewhat interesting - assumeUTF. After reading 
through the docs, it failed my criteria since it had no 
validation - as its name states, it simply assumes that whatever 
you give it is correctly encoded. I didn't expect much here 
anyways, it would have been an odd place to put this 
functionality.

On to the third package that seemed related to my problem: 
std.encoding.
The function that seemed most obvious to do what I wanted to do 
was called "decode".
Well... it decodes a single code point. Really inconvenient. It 
then goes on to state that it supersedes std.utf.decode, but I 
don't remember reading any notice in std.utf.decode that it 
actually was superseded and I shouldn't even really bother trying 
to learn about it, weird but okay. It also helpfully notes that 
codePoints() is more convenient than it. So let's look at that.
Alright, the example shows that codePoints() wants a string or a 
range of chars. I only have a range of bytes, and I would like to 
validate it, not type-system-breaking-cast it. Doesn't seem like 
this function is helpful, but maybe I'm missing something.

Scrolling a bit further, there is an EncodingScheme class. It has 
a neat function, isValid. So after reading a bit on it, what I 
ended up with was: 
EncodingScheme.create("UTF-8").isValid(decodedBase64) followed by 
a type-system-ignoring cast from ubyte[] to char[] (since I now 
know it is valid so this cast is fine). All in all, including the 
explicit error handling required by isValid this has taken about 
an hour of research and 7 lines of code.
In a language with far less abstraction capabilities (namely C#) 
the following would've done the trick, throwing an exception on 
failure:
Encoding.UTF8.GetString(Convert.FromBase64String("base64"))

Looking back the things that really slowed me down here were:
-The lack of an answer on StackOverflow to this very specific 
problem (otherwise this would have been the job of 5 minutes, if 
even)
-The lack of examples for specific functions in the documentation
-The relative difficulty navigating the documentation (often 
times 10 or more functions on a single page) as well as very 
densely written documentation (I often find myself reading 
sentences twice or more just to extract all information from 
them, since single sentences often contain multiple important 
facts)

As this isn't really a question for Learn I'm not sure if it fits 
here. This is more of a "This is how I went about trying to learn 
X. These are the problems I encountered. Ideas to improve?" but I 
guess I might as well post it here.

So with that in mind, any ideas to improve the situation (that do 
not require 500 man-decades of work)?