docs: Documentation tweaks.

Author: amunra

BUILD.md

@@ -38,7 +38,7 @@ Visual Studio Code should also work well provided you have the "C/C++",
 ## Build outputs
 
 The build will generate libraries compiled to `./build`
-(or your otherwise selected build directory).
+(or your otherwise selected CMake build directory).
 
 You will find one dynamic library and depending on
 the operating system either one or two static libraries.
@@ -85,5 +85,5 @@ libraries against a live instance of QuestDB you need to:
 Delete the `./build` directory.
 
 ```bash
-$ rm -fR build
+$ rm -fR build  # or your otherwise selected CMake build directory.
 ```

CMakeLists.txt

@@ -127,6 +127,7 @@ add_test(
 # System testing Python3 script.
 # This will download the latest QuestDB instance from Github,
 # thus will also require a Java 11 installation to run the tests.
+option(QUESTDB_SYSTEM_TESTING "Run system tests" OFF)
 if(QUESTDB_SYSTEM_TESTING)
     find_package(
         Python3

DEPENDENCY.md

@@ -10,7 +10,7 @@ how we tag releases.
 
 We do not ship binaries.
 
-Instead you should obtain a copy of the code sync'ed up
+Instead you should rely on a copy of the code sync'ed up
 to the latest annotated tag. You can find the list of tags on
 the [project's GitHub tag page](tags) or by listing the annotated tags in git
 from a checked out copy of the code.
@@ -22,8 +22,8 @@ git tag -n99 --sort=-creatordate
 
 Examples below will use a dummy name of `CHOSEN_RELEASE_TAG` that you will have
 to substitute for one of these tag names. During development you may also
-substitute it to a specific commit or just `main`, but we don't recommend this
-for production use.
+substitute it to a specific commit or just `main`, but we don't recommend
+running non-tagged code for production use.
 
 ## Getting notified of new releases
 
@@ -32,7 +32,8 @@ our [community page](https://questdb.io/community/).
 
 ## main.cpp
 
-We will cover various approaches.
+We will cover various approaches of including `c-questdb-client` into your
+project.
 
 In all examples below, we will attempt to compile:
 
@@ -50,8 +51,8 @@ int main()
 ## Option 1: CMake & FetchContent integration
 
 If your project already uses CMake, you may use its `FetchContent` feature to
-automatically clone the repository into your build directory when compiling your
-project.
+automatically clone the repository into your temporary build directory when
+compiling your project.
 
 Approach upsides:
 * Easiest setup.
@@ -65,8 +66,9 @@ Approach downsides:
 * Slightly slows down your clean-build time as it runs `git clone` every time
   you configure your CMake project (no impact on rebuild).
 
-In the example CMake below, you need to substitute `CHOSEN_RELEASE_TAG` for one
-of our releases. Don't forget to also update `your_project_name`.
+In the example `CMakeLists.txt` configuration below, you need to substitute
+`CHOSEN_RELEASE_TAG` for one of our releases. Don't forget to also update
+`your_project_name`.
 
 ```cmake
 # CMakeLists.txt
@@ -119,7 +121,8 @@ Grafting can be accomplished via either one of:
 Pick either approach to obtain a copy of this library's code into
 the `deps/c-questdb-client` directory within your git repository.
 
-Once done, the `CMakeLists.txt` config is the same.
+Once done, [configuring `CMakeLists.txt`](cmakeliststxt_with_subdirectory)
+config is the same.
 
 ### Grafting via `git subtree` (recommended)
 
@@ -142,7 +145,8 @@ from the command below and run it from your project's root:
 git subtree add --prefix deps/c-questdb-client https://github.com/questdb/c-questdb-client.git CHOSEN_RELEASE_TAG --squash
 ```
 
-Anyone else in the team who will `git clone` your repo will get all files.
+Anyone else in the team who will `git clone` your repo will obtain all necessary
+files to build the project without additional steps.
 
 At a later date, to upgrade to a newer release (or to revert back to an older
 one) pick a new release tag and run the following command, editing
@@ -197,7 +201,7 @@ git add deps/c-questdb-client
 git commit -m "Updated submodule: c-questdb-client @ NEWLY_CHOSEN_RELEASE_TAG"
 ```
 
-### CMakeLists.txt
+### CMakeLists.txt with subdirectory
 
 Now that our library's code is accessible within your project's
 `deps/c-questdb-client` path we will try and build with it.

README.md

@@ -82,19 +82,19 @@ The following is a non-exhaustive of guidelines to follow:
 * For a given row, a column name should not be repeated.
   If it's repeated, only the first value will be kept.
   This also applies to symbols.
-* Values for a given colum should always have the same type.
+* Values for a given column should always have the same type.
   If changing types the whole row will be dropped (unless we can cast).
 * If supplying timestamps these need to be at least equal to
   previous ones in the same table, unless using the out of order
-  feature. Such rows would be dropped.
+  feature. Out of order rows would be dropped.
 * The timestamp column should be written out through the provided
   `line_sender_at` function (in C) or or `.at()` method in (C++).
   It is also possible to write out additional timestamps values
   as columns.
 
 *Refer to the
 [protocol reference docs](https://questdb.io/docs/reference/api/ilp/overview/)
-for details and more usage guidelines.*
+for more details and usage guidelines.*
 
 ### Data type conversions
 
@@ -103,6 +103,9 @@ that the set supported by QuestDB.
 We map these types into QuestDB types and perform conversions
 as necessary wherever possible.
 
+For more details see our
+[datatypes](https://questdb.io/docs/reference/sql/datatypes) page.
+
 ## Building this library
 
 We do not ship binaries. To build, prepare your system with:
@@ -223,11 +226,12 @@ Note how if you're using C++, `.close()` can be called multiple times and will
 also be called automatically on object destruction.
 
 For simplicity the the diagram above does not show that the `.close()` method
-and the `~line_sender` destructor.
+and the `~line_sender` destructor at any time.
 
 Note that most methods in C++ may throw `questdb::ilp::line_sender_error`
 exceptions. The C++ `line_sender_error` type inherits from `std::runtime_error`
-and you can obtain an error message description by calling `.what()`.
+and you can obtain an error message description by calling `.what()` and an
+error code calling `.code()`.
 
 #### Resuming after an error
 
@@ -249,12 +253,12 @@ For more details see our
 
 ## If you don't see any data
 
-You may be experiencing one of these three issues.
+You may be experiencing one of these issues:
 
 ### QuestDB configuration
 
 If you can't initially see your data through a `select` query straight away,
-his is normal: by default the database will only commit data it receives
+this is normal: by default the database will only commit data it receives
 though the line protocol periodically to maximize throughput.
 
 For dev/testing you may want to tune the following database configuration