Doc: Enforce comment-after-code rule

Install capnp-json.pc

[ 66%] Linking CXX executable capnpc-c++
cd /home/edward.catmur/build/capnproto@master/c++/src/capnp && /usr/local/bin/cmake -E cmake_link_script CMakeFiles/capnpc_cpp.dir/link.txt --verbose=1
/usr/lib64/icecc/bin/c++   -fsanitize=vptr   CMakeFiles/capnpc_cpp.dir/compiler/capnpc-c++.c++.o  -o capnpc-c++ -rdynamic libcapnp.a ../kj/libkj.a -lpthread
libcapnp.a(layout.c++.o):(.data+0x38): undefined reference to `typeinfo for capnp::ClientHook'
libcapnp.a(layout.c++.o):(.data+0x3b8): undefined reference to `typeinfo for capnp::ClientHook'
collect2: error: ld returned 1 exit status

$ g++ --version
g++ (GCC) 5.4.0
Copyright (C) 2015 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

While comments should appear after the code, some examples violate the convention. This commit enforces the rule.

Minor: fix typo in `capnp help encode` documentation

Add versioning to the libraries in the CMake build

The Autotools and CMake builds are almost the same, except for
the libraries not being generated as versioned libraries in CMake.

Fixing this lets Linux CMake builds be on the same level as Autotools ones.

Add cmake_minimum_required to root CMakeLists.txt

There was already a minimum version specified in the actual CMakeLists
file in the C++ directory, but since the parent file does not have it
you get a warning if you build in the idiomatic cmake fashion:

    mkdir build
    cd build
    cmake .. # <---- warning here because no minimum version specified

I used 3.1 as min version because that is the same as specified in child
file.

This reverts commit b50f6598.

Merge branch 'doccomments' of https://github.com/opensourcerouting/capnproto into opensourcerouting-doccomments

Fix MSVC build error when using List<T> with generic T

Add CMakeLists.txt to top level

Tweaks and bugfixes

It turns out that, quite often, the write() will have already completed before the method returns, hence dropping the returned promise won't cause any apparent problem -- until you try to write() a sufficiently large value that it doesn't complete on the first call. Then, you get mysterious bugs.

Indeed, it turns out the HTTP library has such bugs, which are fixed in this change.

std::initializer_list is problematic because it insists that its elements be const, meaning among other things that you can't move from them. So, an std::initializer_list<kj::String> is often useless. With kj::arr you can do like:

    kj::Array<String> = kj::arr(kj::mv(string1), kj::mv(string2));

This requires C++17 due to the fold expression. This could maybe be worked around using some ugly recursion but I'm writing C++17 these days so meh.

I'm increasingly thinking that maybe kj::Array itself should support Vector semantics, but for now this change makes it easier to write code that uses Vector instead of Array.

Actually add URL library to makefiles