Update docs (#120)

* Updated documentation

* Updated example in README.md

Author: glynos

CMakeLists.txt

@@ -8,7 +8,7 @@ cmake_minimum_required(VERSION 3.14)
 
 project(
         skyr-url
-        VERSION 1.10.0
+        VERSION 1.11.0
         HOMEPAGE_URL https://cpp-netlib.github.io/url
         DESCRIPTION "A C++ library that implements the WhatWG URL specification"
         LANGUAGES CXX

README.md

@@ -11,7 +11,6 @@
 [![AppVeyor](https://ci.appveyor.com/api/projects/status/1iblsi5apka29dmg?svg=true)](
     https://ci.appveyor.com/project/glynos/url-3aeqd)
 
-
 ## Introduction
 
 This library provides:
@@ -62,7 +61,7 @@ Using `vcpkg`, install the library dependencies:
 > ./vcpkg install tl-expected catch2 nlohmann-json fmt
 ```
 
-### Building with `CMake` and `Ninja`
+### Building the project with `CMake` and `Ninja`
 
 From a terminal, execute the following sequence of commands:
 
@@ -82,101 +81,112 @@ To run the tests:
 > cmake --build _build --target test
 ```
 
-On Windows, replace the target with ``RUN_TESTS``.
+On Windows, replace the target with ``RUN_TESTS``:
+
+```powershell
+> cmake --build _build --target RUN_TESTS
+```
 
 To install the library:
 
 ```bash
 > cmake --build _build --target install
 ```
 
-## Examples
+## Testing and installing the project
 
-These examples are based on the
-[WhatWG API specification](https://url.spec.whatwg.org/#example-5434421b)
-
-To build the examples with the sources, run `cmake` as follows:
+### Installing with `CMake` and `Ninja`
 
 ```bash
 > cmake .. \
     -G "Ninja" \
-    -DSkyr_BUILD_EXAMPLES=ON \
-    -DCMAKE_TOOLCHAIN_FILE=${VCPKG_ROOT}/vcpkg/scripts/buildsystems/vcpkg.cmake
+    -DCMAKE_TOOLCHAIN_FILE=${VCPKG_ROOT}/vcpkg/scripts/buildsystems/vcpkg.cmake \
+    -DCMAKE_INSTALL_PREFIX=$PREFIX
+> ninja
+> ninja test
+> ninja install
 ```
 
-### Creating a URL without a base URL
+Where `$PREFIX` is the location where you want to install the
+library. Depending on the location of `$PREFIX`, you may need to run
+the install command as an administrator (e.g. on Linux as `sudo`).
+
+
+## Example usage
+
+### Source code
 
-[This example](examples/example_01.md) parses a string,
-"https://example.org/💩", without using a base URL:
+Here is an example of how to use the ``skyr::url`` class to parse a
+URL string and to process the components:
 
 ```c++
+// url_parts.cpp
+
 #include <skyr/url.hpp>
+#include <skyr/percent_encoding/percent_decode.hpp>
 #include <iostream>
 
-int main(int argc, char *argv[]) {
-  auto url = skyr::url("http://example.org/\xf0\x9f\x92\xa9");
-  std::cout << url.pathname() << std::endl;
-}
-```
+int main() {
+  using namespace skyr::literals;
 
-Gives the output: `/%F0%9F%92%A9`
+  auto url =
+      "http://sub.example.إختبار:8090/\xcf\x80?a=1&c=2&b=\xe2\x80\x8d\xf0\x9f\x8c\x88"_url;
 
-### Creating a non-absolute URL without a base URL
+  std::cout << "Protocol: " << url.protocol() << std::endl;
 
-[This example](examples/example_02.md)  gives an error if
-the input, "/🍣🍺", is not an *absolute-URL-with-fragment-string*:
+  std::cout << "Domain?   " << std::boolalpha << url.is_domain() << std::endl;
+  std::cout << "Domain:   " << url.hostname() << std::endl;
+  std::cout << "Domain:   "
+            << skyr::domain_to_unicode(url.hostname()).value() << std::endl;
 
-```c++
-#include <skyr/url.hpp>
-#include <iostream>
+  std::cout << "Port:     " << url.port<std::uint16_t>().value() << std::endl;
+
+  std::cout << "Pathname: "
+            << skyr::percent_decode<std::string>(url.pathname()).value() << std::endl;
 
-int main(int argc, char *argv[]) {
-  auto url = skyr::make_url("\xf0\x9f\x8d\xa3\xf0\x9f\x8d\xba");
-  if (!url) {
-    std::cerr << "Parsing failed: " << url.error().message() << std::endl;
+  std::cout << "Search parameters:" << std::endl;
+  const auto &search = url.search_parameters();
+  for (const auto &[key, value] : search) {
+    std::cout << "  " << "key: " << key << ", value = " << value << std::endl;
   }
 }
 ```
 
-This gives the output: `Parsing failed: Not an absolute URL with fragment`
+### Build script
 
-### Creating a non-absolute URL with a base URL
+Here is the ``CMake`` script to build the example:
 
-[This example](examples/example_03.md) parses a string,
-"🏳️‍🌈", using a base URL, "https://example.org/":
+```cmake
+# CMakeLists.txt
 
-```c++
-#include <skyr/url.hpp>
-#include <iostream>
+project(my_project)
 
-int main(int argc, char *argv[]) {
-  auto base = skyr::url("https://example.org/");
-  auto url = skyr::url(
-    "\xf0\x9f\x8f\xb3\xef\xb8\x8f\xe2\x80\x8d\xf0\x9f\x8c\x88", base);
-  std::cout << url.href() << std::endl;
-}
-```
+find_package(tl-expected CONFIG REQUIRED)
+find_package(skyr-url CONFIG REQUIRED)
 
-This gives the output: `https://example.org/%F0%9F%8F%B3%EF%B8%8F%E2%80%8D%F0%9F%8C%88`
+set(CMAKE_CXX_STANDARD 17)
 
-## Testing and installation
+add_executable(url_parts url_parts.cpp)
+target_link_libraries(url_test PRIVATE skyr::skyr-url)
+```
 
-### Installing with `CMake` and `Ninja`
+### Output
+
+The output of this program is:
 
 ```bash
-> cmake .. \
-    -G "Ninja" \
-    -DCMAKE_TOOLCHAIN_FILE=${VCPKG_ROOT}/vcpkg/scripts/buildsystems/vcpkg.cmake \
-    -DCMAKE_INSTALL_PREFIX=$PREFIX
-> ninja
-> ninja test
-> ninja install
+Protocol: http:
+Domain?   true
+Domain:   sub.example.xn--kgbechtv
+Domain:   sub.example.إختبار
+Port:     8090
+Pathname: /π
+Search parameters:
+  key: a, value = 1
+  key: c, value = 2
+  key: b, value = ‍🌈
 ```
 
-Where `$PREFIX` is the location where you want to install the
-library. Depending on the location of `$PREFIX`, you may need to run
-the install command as an administrator (e.g. on Linux as `sudo`).
-
 ## Dependencies
 
 This library uses [expected](https://github.com/TartanLlama/expected).

docs/Doxyfile.in

@@ -829,13 +829,13 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = @PROJECT_SOURCE_DIR@/include/skyr/ \
-                         @PROJECT_SOURCE_DIR@/include/skyr/core/ \
-                         @PROJECT_SOURCE_DIR@/include/skyr/domain/ \
-                         @PROJECT_SOURCE_DIR@/include/skyr/network/ \
-                         @PROJECT_SOURCE_DIR@/include/skyr/percent_encoding/ \
-                         @PROJECT_SOURCE_DIR@/include/skyr/filesystem/ \
-                         @PROJECT_SOURCE_DIR@/include/skyr/json/
+INPUT                  = @PROJECT_SOURCE_DIR@/include/skyr/v1/ \
+                         @PROJECT_SOURCE_DIR@/include/skyr/v1/core/ \
+                         @PROJECT_SOURCE_DIR@/include/skyr/v1/domain/ \
+                         @PROJECT_SOURCE_DIR@/include/skyr/v1/network/ \
+                         @PROJECT_SOURCE_DIR@/include/skyr/v1/percent_encoding/ \
+                         @PROJECT_SOURCE_DIR@/include/skyr/v1/filesystem/ \
+                         @PROJECT_SOURCE_DIR@/include/skyr/v1/json/
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

docs/conf.py.in

@@ -26,13 +26,13 @@ project = 'Skyr URL'
 copyright = '2018-20, Glyn Matthews'
 author = 'Glyn Matthews'
 
-major, minor, patch, sha1 = @skyr-url_VERSION_MAJOR@, @skyr-url_VERSION_MINOR@, @skyr-url_VERSION_PATCH@, @skyr-url_VERSION_SHA1@
+major, minor, patch = @skyr-url_VERSION_MAJOR@, @skyr-url_VERSION_MINOR@, @skyr-url_VERSION_PATCH@
 
 
 # The short X.Y version
 version = '{}.{}'.format(major, minor)
 # The full version, including alpha/beta/rc tags
-release = '{}.{}.{}-{}}'.format(major, minor, patch, sha1)
+release = '{}.{}.{}'.format(major, minor, patch)
 
 
 # -- General configuration ---------------------------------------------------

docs/core.rst

@@ -4,14 +4,13 @@ Core
 Description
 -----------
 
-The core of the `skyr` library is a `skyr::url_record` that
-contains a URL parts, a `skyr::parse` function that parses an
-input string and creates a `skyr::url_record` and a
-`skyr::serialize` function that composes a URL string from an
-existing `skyr::url_record`.
+The core of the ``skyr`` library is a ``skyr::parse`` function
+that parses an input string and creates a ``skyr::url_record``
+that contains a URL parts, and a ``skyr::serialize`` function
+that composes a URL string from an existing ``skyr::url_record``.
 
 Use these functions directly if your needs are simple. Use the
-`skyr::url` class for more complex operations, including
+``skyr::url`` class for more complex operations, including
 Unicode encoding and decoding.
 
 Headers
@@ -38,7 +37,7 @@ Example
       auto url = skyr::url_parse("http://example.org/");
       std::cout << url << std::endl;
       std::cout << "Scheme:     " << url.scheme << std::endl;
-      std::cout << "Hostname:   " == url.host.value());
+      std::cout << "Hostname:   " << url.host.value().to_string());
       std::cout << "Pathname:   ";
       for (const auto &path : url.path) {
         << std::cout << "/" << path;
@@ -51,17 +50,29 @@ Example
 API
 ---
 
-`skyr::url_record` class
-^^^^^^^^^^^^^^^^^^^^^^^^
+``skyr::host`` class
+^^^^^^^^^^^^^^^^^^^^
+
+.. doxygenclass:: skyr::v1::host
+    :members:
+
+``skyr::url_record`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. doxygenclass:: skyr::v1::url_record
     :members:
 
-`skyr::url_record` functions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``skyr::url_record`` functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. doxygenfunction:: skyr::swap(url_record&, url_record&)
 
-.. doxygenfunction:: skyr::parse
+.. doxygenfunction:: skyr::parse(std::string_view)
+
+.. doxygenfunction:: skyr::parse(std::string_view, bool *)
+
+.. doxygenfunction:: skyr::parse(std::string_view, const url_record&)
+
+.. doxygenfunction:: skyr::parse(std::string_view, const url_record&, bool *)
 
 .. doxygenfunction:: skyr::serialize

docs/domain.rst

@@ -40,13 +40,6 @@ Example
 API
 ---
 
-Punycode
-^^^^^^^^
-
-.. doxygenfunction:: skyr::punycode_encode(std::string_view)
-
-.. doxygenfunction:: skyr::punycode_decode(std::string_view)
-
 Domain to ASCII
 ^^^^^^^^^^^^^^^
 

docs/index.rst

@@ -58,7 +58,7 @@ and standard library.
        std::cout << "Protocol: " << url.protocol() << std::endl;
 
        std::cout << "Domain?   " << std::boolalpha << url.is_domain() << std::endl;
-       std::cout << "Domain:   " << url.domain().value() << std::endl;
+       std::cout << "Domain:   " << url.hostname() << std::endl;
 
        std::cout << "Pathname: " <<
            skyr::percent_decode<std::string>(url.pathname()).value() << std::endl;

docs/network.rst

@@ -28,7 +28,7 @@ Example
 
      auto url = "http://[1080:0:0:0:8:800:200C:417A]:8090/"_url;
      assert(url.is_ipv6_address());
-     std::cout << "IPv6 Host: " << url.ipv6_address().to_string() << std::endl;
+     std::cout << "IPv6 Host: " << urlhostname() << std::endl;
    }
 
 API

docs/url.rst

@@ -4,9 +4,9 @@ URL
 Description
 -----------
 
-The `skyr::url` class parses a URL in the constructor and provides
+The ``skyr::url`` class parses a URL in the constructor and provides
 a rich interface to access and process the URL components. The
-`skyr::url` constructor throws a `skyr::url_parse_error` on failure.
+``skyr::url`` constructor throws a ``skyr::url_parse_error`` on failure.
 
 Headers
 -------
@@ -41,31 +41,31 @@ Example
 API
 ---
 
-`skyr::url` class
-^^^^^^^^^^^^^^^^^
+``skyr::url`` class
+^^^^^^^^^^^^^^^^^^^
 
 .. doxygenclass:: skyr::v1::url
     :members:
 
-`skyr::url` functions
-^^^^^^^^^^^^^^^^^^^^^
+``skyr::url`` functions
+^^^^^^^^^^^^^^^^^^^^^^^
 
 .. doxygenfunction:: skyr::swap(url&, url&)
 
 .. doxygenfunction:: skyr::make_url(const Source&)
 
 .. doxygenfunction:: skyr::make_url(const Source&, const url&)
 
-`skyr::url` error codes
-^^^^^^^^^^^^^^^^^^^^^^^
+``skyr::url`` error codes
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. doxygenenum:: skyr::url_parse_errc
+.. doxygenenum:: skyr::v1::url_parse_errc
 
 .. doxygenclass:: skyr::v1::url_parse_error
     :members:
 
-`skyr::url_search_parameters` class
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``skyr::url_search_parameters`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. doxygenclass:: skyr::v1::url_search_parameters
     :members: