Meta: documentation fixes (machinezone#127)

* Clarify versions, minor punctuation fix

* Copyediting, borked URL

* Fix Python comments in C++ code

* Copyediting

* Pretty code

* Copyediting, pretty code

* Typo

* Pretty code

Author: LunarWatcher

README.md

@@ -1,16 +1,16 @@
 ## Hello world
 
-![Alt text](https://travis-ci.org/machinezone/IXWebSocket.svg?branch=master)
+![Build status badge](https://travis-ci.org/machinezone/IXWebSocket.svg?branch=master)
 
 IXWebSocket is a C++ library for WebSocket client and server development. It has minimal dependencies (no boost), is very simple to use and support everything you'll likely need for websocket dev (SSL, deflate compression, compiles on most platforms, etc...). HTTP client and server code is also available, but it hasn't received as much testing.
 
 It is been used on big mobile video game titles sending and receiving tons of messages since 2017 (iOS and Android). It was tested on macOS, iOS, Linux, Android, Windows and FreeBSD. Two important design goals are simplicity and correctness.
 
 ```cpp
-# Required on Windows
+// Required on Windows
 ix::initNetSystem();
 
-# Our websocket object
+// Our websocket object
 ix::WebSocket webSocket;
 
 std::string url("ws://localhost:8080/");
@@ -34,8 +34,8 @@ webSocket.start();
 webSocket.send("hello world");
 ```
 
-Interested ? Go read the [docs](https://machinezone.github.io/IXWebSocket/) ! If things don't work as expected, please create an issue in github, or even better a pull request if you know how to fix your problem.
+Interested? Go read the [docs](https://machinezone.github.io/IXWebSocket/)! If things don't work as expected, please create an issue on GitHub, or even better a pull request if you know how to fix your problem.
 
-IXWebSocket is actively being developed, check out the [changelog](CHANGELOG.md) to know what's cooking. If you are looking for a real time messaging service (the chat-like 'server' your websocket code will talk to) with many features such as history, backed by Redis, look at [cobra](https://github.com/machinezone/cobra).
+IXWebSocket is actively being developed, check out the [changelog](https://machinezone.github.io/IXWebSocket/CHANGELOG/) to know what's cooking. If you are looking for a real time messaging service (the chat-like 'server' your websocket code will talk to) with many features such as history, backed by Redis, look at [cobra](https://github.com/machinezone/cobra).
 
 IXWebSocket client code is autobahn compliant beginning with the 6.0.0 version. See the current [test results](https://bsergean.github.io/IXWebSocket/autobahn/index.html). Some tests are still failing in the server code.

docs/build.md

@@ -33,7 +33,7 @@ vcpkg install ixwebsocket
 
 ### Conan
 
-Support for building with conan was contributed by Olivia Zoe (thanks !). The package name to reference is `IXWebSocket/5.0.0@LunarWatcher/stable`. The package is in the process to be published to the official conan package repo, but in the meantime, it can be accessed by adding a new remote
+Support for building with conan was contributed by Olivia Zoe (thanks!). The package name to reference is `IXWebSocket/5.0.0@LunarWatcher/stable`, and a list of the uploaded versions is available on [Bintray](https://bintray.com/oliviazoe0/conan-packages/IXWebSocket%3ALunarWatcher). The package is in the process to be published to the official conan package repo, but in the meantime, it can be accessed by adding a new remote
 
 ```
 conan remote add remote_name_here https://api.bintray.com/conan/oliviazoe0/conan-packages

docs/cobra.md

@@ -8,7 +8,7 @@ Bring up 3 terminals and run a server, a publisher and a subscriber in each one.
 
 You will need to have a redis server running locally. To run the server:
 
-```
+```bash
 $ cd <ixwebsocket-top-level-folder>/ixsnake/ixsnake
 $ ws snake
 {
@@ -33,7 +33,7 @@ redis port: 6379
 
 ### Publisher
 
-```
+```bash
 $ cd <ixwebsocket-top-level-folder>/ws
 $ ws cobra_publish --appkey FC2F10139A2BAc53BB72D9db967b024f --endpoint ws://127.0.0.1:8008 --rolename _pub --rolesecret 1c04DB8fFe76A4EeFE3E318C72d771db test_channel cobraMetricsSample.json
 [2019-11-27 09:06:12.980] [info] Publisher connected
@@ -49,7 +49,7 @@ $ ws cobra_publish --appkey FC2F10139A2BAc53BB72D9db967b024f --endpoint ws://127
 
 ### Subscriber
 
-```
+```bash
 $ ws cobra_subscribe --appkey FC2F10139A2BAc53BB72D9db967b024f --endpoint ws://127.0.0.1:8008 --rolename _pub --rolesecret 1c04DB8fFe76A4EeFE3E318C72d771db test_channel
 #messages 0 msg/s 0
 [2019-11-27 09:07:39.341] [info] Subscriber connected

docs/design.md

@@ -24,7 +24,7 @@ Large frames are broken up into smaller chunks or messages to avoid filling up t
 
 The library has an interactive tool which is handy for testing compatibility ith other libraries. We have tested our client against Python, Erlang, Node.js, and C++ websocket server libraries.
 
-The unittest tries to be comprehensive, and has been running on multiple platoform, with different sanitizers such as thread sanitizer to catch data races or the undefined behavior sanitizer.
+The unittest tries to be comprehensive, and has been running on multiple platforms, with different sanitizers such as a thread sanitizer to catch data races or the undefined behavior sanitizer.
 
 The regression test is running after each commit on travis.
 

docs/index.md

@@ -13,11 +13,11 @@
 
 ## Example code
 
-```
-# Required on Windows
+```cpp
+// Required on Windows
 ix::initNetSystem();
 
-# Our websocket object
+// Our websocket object
 ix::WebSocket webSocket;
 
 std::string url("ws://localhost:8080/");
@@ -40,12 +40,12 @@ webSocket.start();
 webSocket.send("hello world");
 ```
 
-## Why another library ?
+## Why another library?
 
 There are 2 main reasons that explain why IXWebSocket got written. First, we needed a C++ cross-platform client library, which should have few dependencies. What looked like the most solid one, [websocketpp](https://github.com/zaphoyd/websocketpp) did depend on boost and this was not an option for us. Secondly, there were other available libraries with fewer dependencies (C ones), but they required calling an explicit poll routine periodically to know if a client had received data from a server, which was not elegant.
 
 We started by solving those 2 problems, then we added server websocket code, then an HTTP client, and finally a very simple HTTP server.
 
 ## Contributing
 
-IXWebSocket is developed on [github](https://github.com/machinezone/IXWebSocket). We'd love to hear about how you use it ; opening up an issue in github is ok for that. If things don't work as expected, please create an issue in github, or even better a pull request if you know how to fix your problem.
+IXWebSocket is developed on [GitHub](https://github.com/machinezone/IXWebSocket). We'd love to hear about how you use it; opening up an issue on GitHub is ok for that. If things don't work as expected, please create an issue on GitHub, or even better a pull request if you know how to fix your problem.

docs/usage.md

@@ -6,7 +6,7 @@ The [*ws*](https://github.com/machinezone/IXWebSocket/tree/master/ws) folder cou
 
 To use the network system on Windows, you need to initialize it once with *WSAStartup()* and clean it up with *WSACleanup()*. We have helpers for that which you can use, see below. This init would typically take place in your main function.
 
-```
+```cpp
 #include <ixwebsocket/IXNetSystem.h>
 
 int main()
@@ -22,12 +22,12 @@ int main()
 
 ## WebSocket client API
 
-```
+```cpp
 #include <ixwebsocket/IXWebSocket.h>
 
 ...
 
-# Our websocket object
+// Our websocket object
 ix::WebSocket webSocket;
 
 std::string url("ws://localhost:8080/");
@@ -82,9 +82,9 @@ If the connection was closed and sending failed, the return value will be set to
 
 ### Open and Close notifications
 
-The onMessage event will be fired when the connection is opened or closed. This is similar to the [Javascript browser API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket), which has `open` and `close` events notification that can be registered with the browser `addEventListener`.
+The onMessage event will be fired when the connection is opened or closed. This is similar to the [JavaScript browser API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket), which has `open` and `close` events notification that can be registered with the browser `addEventListener`.
 
-```
+```cpp
 webSocket.setOnMessageCallback([](const ix::WebSocketMessagePtr& msg)
     {
         if (msg->type == ix::WebSocketMessageType::Open)
@@ -115,7 +115,7 @@ webSocket.setOnMessageCallback([](const ix::WebSocketMessagePtr& msg)
 
 A message will be fired when there is an error with the connection. The message type will be `ix::WebSocketMessageType::Error`. Multiple fields will be available on the event to describe the error.
 
-```
+```cpp
 webSocket.setOnMessageCallback([](const ix::WebSocketMessagePtr& msg)
     {
         if (msg->type == ix::WebSocketMessageType::Error)
@@ -140,7 +140,7 @@ webSocket.setOnMessageCallback([](const ix::WebSocketMessagePtr& msg)
 
 The url can be set and queried after a websocket object has been created. You will have to call `stop` and `start` if you want to disconnect and connect to that new url.
 
-```
+```cpp
 std::string url("wss://example.com");
 websocket.configure(url);
 ```
@@ -149,7 +149,7 @@ websocket.configure(url);
 
 Ping/pong messages are used to implement keep-alive. 2 message types exists to identify ping and pong messages. Note that when a ping message is received, a pong is instantly send back as requested by the WebSocket spec.
 
-```
+```cpp
 webSocket.setOnMessageCallback([](const ix::WebSocketMessagePtr& msg)
     {
         if (msg->type == ix::WebSocketMessageType::Ping ||
@@ -163,7 +163,7 @@ webSocket.setOnMessageCallback([](const ix::WebSocketMessagePtr& msg)
 
 A ping message can be sent to the server, with an optional data string.
 
-```
+```cpp
 websocket.ping("ping data, optional (empty string is ok): limited to 125 bytes long");
 ```
 
@@ -173,15 +173,15 @@ You can configure an optional heart beat / keep-alive, sent every 45 seconds
 when there is no any traffic to make sure that load balancers do not kill an
 idle connection.
 
-```
+```cpp
 webSocket.setHeartBeatPeriod(45);
 ```
 
 ### Supply extra HTTP headers.
 
 You can set extra HTTP headers to be sent during the WebSocket handshake.
 
-```
+```cpp
 WebSocketHttpHeaders headers;
 headers["foo"] = "bar";
 webSocket.setExtraHeaders(headers);
@@ -191,22 +191,22 @@ webSocket.setExtraHeaders(headers);
 
 You can specify subprotocols to be set during the WebSocket handshake. For more info you can refer to [this doc](https://hpbn.co/websocket/#subprotocol-negotiation).
 
-```
+```cpp
 webSocket.addSubprotocol("appProtocol-v1");
 webSocket.addSubprotocol("appProtocol-v2");
 ```
 
 The protocol that the server did accept is available in the open info `protocol` field.
 
-```
+```cpp
 std::cout << "protocol: " << msg->openInfo.protocol << std::endl;
 ```
 
 ### Automatic reconnection
 
 Automatic reconnection kicks in when the connection is disconnected without the user consent. This feature is on by default and can be turned off.
 
-```
+```cpp
 webSocket.enableAutomaticReconnection();  // turn on
 webSocket.disableAutomaticReconnection(); // turn off
 bool enabled = webSocket.isAutomaticReconnectionEnabled(); // query state
@@ -239,7 +239,7 @@ Wait time(ms): 10000
 
 The waiting time is capped by default at 10s between 2 attempts, but that value can be changed and queried.
 
-```
+```cpp
 webSocket.setMaxWaitBetweenReconnectionRetries(5 * 1000); // 5000ms = 5s
 uint32_t m = webSocket.getMaxWaitBetweenReconnectionRetries();
 ```
@@ -253,7 +253,7 @@ Then, secure sockets are automatically used when connecting to a `wss://*` url.
 Additional TLS options can be configured by passing a `ix::SocketTLSOptions` instance to the
 `setTLSOptions` on `ix::WebSocket` (or `ix::WebSocketServer` or `ix::HttpServer`)
 
-```
+```cpp
 webSocket.setTLSOptions({
     .certFile = "path/to/cert/file.pem",
     .keyFile = "path/to/key/file.pem",
@@ -279,7 +279,7 @@ For a server, specifying `caFile` implies that:
 
 ## WebSocket server API
 
-```
+```cpp
 #include <ixwebsocket/IXWebSocketServer.h>
 
 ...
@@ -344,7 +344,7 @@ server.wait();
 
 ## HTTP client API
 
-```
+```cpp
 #include <ixwebsocket/IXHttpClient.h>
 
 ...
@@ -427,7 +427,7 @@ bool ok = httpClient.performRequest(args, [](const HttpResponsePtr& response)
 
 ## HTTP server API
 
-```
+```cpp
 #include <ixwebsocket/IXHttpServer.h>
 
 ix::HttpServer server(port, hostname);
@@ -445,7 +445,7 @@ server.wait();
 
 If you want to handle how requests are processed, implement the setOnConnectionCallback callback, which takes an HttpRequestPtr as input, and returns an HttpResponsePtr. You can look at HttpServer::setDefaultConnectionCallback for a slightly more advanced callback example.
 
-```
+```cpp
 setOnConnectionCallback(
     [this](HttpRequestPtr request,
            std::shared_ptr<ConnectionState> /*connectionState*/) -> HttpResponsePtr

docs/ws.md

@@ -245,4 +245,4 @@ Options:
 
 ## Cobra Client
 
-[cobra](https://github.com/machinezone/cobra) is a real time messenging server. ws has sub-command to interacti with cobra.
+[cobra](https://github.com/machinezone/cobra) is a real time messenging server. ws has a sub-command to interact with cobra.