Reformat documentation

CONTRIBUTING.md

@@ -1,16 +1,16 @@
-Contributing to dd-trace-cpp
-============================
+# Contributing to dd-trace-cpp
+
 Pull requests for bug fixes are welcome.
 
 Before submitting new features or changes to current functionality, [open an
-issue](https://github.com/DataDog/dd-trace-cpp/issues/new) and discuss your
-ideas or propose the changes you wish to make. After a resolution is reached, a
-PR can be submitted for review.
+issue](https://github.com/DataDog/dd-trace-cpp/issues/new) and discuss your ideas or propose the
+changes you wish to make. After a resolution is reached, a PR can be submitted for review.
+
+## Code Style
+
+C++ code is formatted using `clang-format-14`. Before submitting code changes, run the following
+command:
 
-Code Style
-----------
-C++ code is formatted using `clang-format-14`. Before submitting code changes,
-run the following command:
-```shell 
-$ bin/format
+```shell
+bin/format
 ```

README.md

@@ -1,5 +1,4 @@
-Datadog C++ Tracing Library
-===========================
+# Datadog C++ Tracing Library
 
 ```c++
 #include <datadog/span_config.h>
@@ -37,26 +36,30 @@ int main() {
     std::this_thread::sleep_for(std::chrono::seconds(2));
 }
 ```
+
 See the [examples](examples) directory for more extensive usage examples.
 
 ## Platform Support
-The library has been tested and is compatible on the following CPU architecture, OS and compiler combinations:
-- x86_64 and arm64 Linux with GCC 11.4.
-- x86_64 and arm64 Linux with Clang 14.
-- x86_64 Windows with MSVC 2022.
-- arm64 macOS with Apple Clang 15.
 
+The library has been tested and is compatible on the following CPU architecture, OS and compiler
+combinations:
+
+- x86_64 and arm64 Linux with GCC 11.4;
+- x86_64 and arm64 Linux with Clang 14;
+- x86_64 Windows with MSVC 2022;
+- arm64 macOS with Apple Clang 15.
 
 ## Building and Installation
 
 ### Requirements
+
 `dd-trace-cpp` requires a [supported](#platform-support) C++17 compiler.
 
-A recent version of CMake is required (`3.28`), which might not be in your
-system's package manager. [bin/install-cmake](bin/install-cmake) is an installer
-for a recent CMake, on Linux.
+A recent version of CMake is required (`3.28`), which might not be in your system's package manager.
+[bin/install-cmake](bin/install-cmake) is an installer for a recent CMake, on Linux.
 
 ### Building
+
 Build this library from source using [CMake](https://cmake.org).
 
 ```shell
@@ -74,6 +77,7 @@ cmake -B build -DBUILD_SHARED_LIBS=1 .
 ```
 
 ### Installation
+
 Installation places a shared library and public headers into the appropriate system directories
 (`/usr/local/[…]`), or to a specified installation prefix. Example:
 
@@ -83,12 +87,13 @@ cmake --install build --prefix=.install
 ```
 
 ### Optional: Linking to the shared library
+
 In case you decided to build the shared library:
 
-When building an executable that uses `dd-trace-cpp`, specify the path to
-the installed headers using an appropriate `-I` option.  If the library was
-installed into the default system directories, then the `-I` option is not
-needed.
+When building an executable that uses `dd-trace-cpp`, specify the path to the installed headers
+using an appropriate `-I` option. If the library was installed into the default system directories,
+then the `-I` option is not needed.
+
 ```shell
 c++ -I/path/to/dd-trace-cpp/.install/include -c -o my_app.o my_app.cpp
 ```
@@ -97,15 +102,17 @@ When linking an executable that uses `dd-trace-cpp`, specify linkage to the
 built library using the `-ldd_trace_cpp` option and an appropriate `-L` option.
 If the library was installed into the default system directories, then the `-L`
 options is not needed. The `-ldd_trace_cpp` option is always needed.
+
 ```shell
 c++ -o my_app my_app.o -L/path/to/dd-trace-cpp/.install/lib -ldd_trace_cpp
 ```
 
-Test
-----
+## Test
+
 Pass `-DDD_TRACE_BUILD_TESTING=1` to `cmake` to include the unit tests in the build.
 
 The resulting unit test executable is `test/tests` within the build directory.
+
 ```shell
 cmake -B build -DDD_TRACE_BUILD_TESTING=1 .
 cmake --build build -j
@@ -114,7 +121,7 @@ cmake --build build -j
 
 Alternatively, [bin/test](bin/test) is provided for convenience.
 
-Contributing
-------------
-See the [contributing guidelines](CONTRIBUTING.md) and the [maintainer docs](doc/maintainers.md)
-for information on the overall structure of the repository.
+## Contributing
+
+See the [contributing guidelines](CONTRIBUTING.md) and the [maintainer docs](doc/maintainers.md) for
+information on the overall structure of the repository.

SECURITY.md

@@ -1,15 +1,19 @@
 # Security Policy
 
-This document outlines the security policy for the Datadog C++ client library (aka C++ tracer) and what to do if you discover a security vulnerability in the project.
-Most notably, please do not share the details in a public forum (such as in a discussion, issue, or pull request) but instead reach out to us with the details.
-This gives us an opportunity to release a fix for others to benefit from by the time details are made public.
+This document outlines the security policy for the Datadog C++ client library (a.k.a. C++ tracer)
+and what to do if you discover a security vulnerability in the project. Most notably, please do not
+share the details in a public forum (such as in a discussion, issue, or pull request) but instead
+reach out to us with the details. This gives us an opportunity to release a fix for others to
+benefit from by the time details are made public.
 
 ## Supported Versions
 
-We accept vulnerability submissions for the [currently maintained release](https://github.com/DataDog/dd-trace-cpp/releases).
+We accept vulnerability submissions for the [currently maintained
+release](https://github.com/DataDog/dd-trace-cpp/releases).
 
 ## Reporting a Vulnerability
 
-If you discover a vulnerability in the Datadog C++ client library (or any Datadog product for that matter) please submit details to the following email address:
+If you discover a vulnerability in the Datadog C++ client library (or any Datadog product for that
+matter) please submit details to the following email address:
 
 * [security@datadoghq.com](mailto:security@datadoghq.com)

benchmark/README.md

@@ -1,19 +1,18 @@
-Microbenchmarks
-===============
-This directory contains the definition of a program that measures the timing and
-resource consumption of a test tracing scenario.
+# Microbenchmarks
 
-The benchmark uses [Google Benchmark][1], whose source is included as a git
-submodule under `./google-benchmark`.
+This directory contains the definition of a program that measures the timing and resource
+consumption of a test tracing scenario.
 
-The scenario that's measured is similar to the [../examples/hasher][3] setup.  A trace
-is created whose structure reflects that of a particular file directory
-structure.  The directory structure, in this case, is the source tree of the
-[Tiny C Compiler][4], whose source is included as a git submodule under
-`./tinycc`.
+The benchmark uses [Google Benchmark](https://github.com/google/benchmark), whose source is included
+as a git submodule under `./google-benchmark`.
 
-The scenario does not use the network, spawn any threads, or read/write
-any files. The operations that are implicitly covered by the scenario are:
+The scenario that's measured is similar to the [../examples/hasher](../examples/hasher) setup. A
+trace is created whose structure reflects that of a particular file directory structure. The
+directory structure, in this case, is the source tree of the [Tiny C
+Compiler](https://bellard.org/tcc), whose source is included as a git submodule under `./tinycc`.
+
+The scenario does not use the network, spawn any threads, or read/write any files. The operations
+that are implicitly covered by the scenario are:
 
 - configuring and initializing a tracer,
 - creating a trace,
@@ -23,14 +22,8 @@ any files. The operations that are implicitly covered by the scenario are:
 - finalizing a trace and making a sampling decision,
 - serializing a trace as MessagePack.
 
-[../bin/benchmark][6] is a script that builds dd-trace-cpp, this benchmark, and
+[../bin/benchmark](../bin/benchmark) is a script that builds `dd-trace-cpp`, this benchmark, and
 then runs the benchmark.
 
-This benchmark is intended to be driven by Datadog's internal benchmarking
-platform.  See [../.gitlab/benchmarks.yml][7].
-
-[1]: https://github.com/google/benchmark
-[3]: ../examples/hasher
-[4]: https://bellard.org/tcc/
-[6]: ../bin/benchmark
-[7]: ../.gitlab/benchmarks.yml
+This benchmark is intended to be driven by Datadog's internal benchmarking platform. See
+[../.gitlab/benchmarks.yml](../.gitlab/benchmarks.yml).

benchmark/hasher.cpp

@@ -3,11 +3,11 @@
 // If the path does not exist, print an error.
 //
 // If the path exists and is a regular file, print the SHA256 digest of the
-// file's contents.  Produce a single tracing span indicating the calculation.
+// file's contents. Produce a single tracing span indicating the calculation.
 //
 // If the path exists and is a directory, calculate the SHA256 digest of the
 // directory from the names and digests of its children, combined in some
-// canonical format.  Produce a trace whose structure reflects the directory
+// canonical format. Produce a trace whose structure reflects the directory
 // structure.
 //
 // Files that are neither regular files nor directories are ignored.
@@ -47,7 +47,7 @@ std::string hex(const Digest &digest) {
 }
 
 // Store into the specified `digest` the SHA256 digest of the contents of the
-// specified `file`.  Return zero on success, or a nonzero value if an error
+// specified `file`. Return zero on success, or a nonzero value if an error
 // occurs.
 int sha256(Digest &digest, const fs::path &file) {
   std::ifstream in(file);

bin/with-toolchain

@@ -9,7 +9,7 @@ usage:
     with-toolchain llvm [COMMAND ...]
         Execute COMMAND in an environment that uses either GNU's compilers (gcc
         and g++) or LLVM's compilers (clang and clang++).
-    
+
     with-toolchain --help
     with-toolchain -h
         Print this message.
@@ -33,7 +33,7 @@ case "$1" in
   llvm)
     toolchain=llvm ;;
   *)
-    >&2 echo "Invalid toolchain value \"$1\".  Expected \"gnu\" or \"llvm\"."
+    >&2 echo "Invalid toolchain value \"$1\". Expected \"gnu\" or \"llvm\"."
     exit 2 ;;
 esac
 

doc/README.md

@@ -1,29 +1,28 @@
-Logical Component Relationships
--------------------------------
+# Logical Component Relationships
+
 - Vertices are components.
-- Edges are ownership relationships between components.  Each edge is labeled
-  by the kind of "smart pointer" that could implement that kind of
-  relationship.
+- Edges are ownership relationships between components. Each edge is labeled by the kind of "smart
+  pointer" that could implement that kind of relationship.
 - Components containing a padlock are protected by a mutex.
 
 ![diagram](ownership.svg)
 
-Objects
--------
-- _Span_ has a beginning, end, and tags.  It is associated with a _TraceSegment_.
-- _TraceSegment_ is part of a trace.  It makes sampling decisions, detects when
-  it is finished, and sends itself to the _Collector_.
-- _Collector_ receives trace segments.  It provides a callback to deliver
-  sampler modifications, if applicable.
-- _Tracer_ is responsible for creating trace segments. It contains the
-  instances of, and configuration for, the _Collector_, _TraceSampler_, and
-  _SpanSampler_.  A tracer is created from a _TracerConfig_.
-- _TraceSampler_ is used by trace segments to decide when to keep or drop
-  themselves.
-- _SpanSampler_ is used by trace segments to decide which spans to keep when
-  the segment is dropped.
-- _TracerConfig_ contains all of the information needed to configure the collector,
-  trace sampler, and span sampler, as well as defaults for span properties.
+## Objects
+
+- `Span` has a beginning, end, and tags. It is associated with a `TraceSegment`.
+- `TraceSegment` is part of a trace. It makes sampling decisions, detects when it is finished, and
+  sends itself to the `Collector`.
+- `Collector` receives trace segments. It provides a callback to deliver sampler modifications, if
+  applicable.
+- `Tracer` is responsible for creating trace segments. It contains the instances of, and
+  configuration for, the `Collector`, `TraceSampler`, and `SpanSampler`. A tracer is created from a
+  `TracerConfig`.
+- `TraceSampler` is used by trace segments to decide when to keep or drop themselves.
+- `SpanSampler` is used by trace segments to decide which spans to keep when the segment is dropped.
+- `TracerConfig` contains all of the information needed to configure the collector, trace sampler,
+  and span sampler, as well as defaults for span properties.
+
+## Usage
 
 Intended usage is:
 
@@ -32,11 +31,8 @@ Intended usage is:
 3. Use the `Tracer` to create and/or extract local root `Span`s.
 4. Use `Span` to create children and/or inject context.
 5. Use a `Span`'s `TraceSegment` to perform trace-wide operations.
-6. When all `Span`s in ` TraceSegment` are finished, the segment is sent to the
+6. When all `Span`s in `TraceSegment` are finished, the segment is sent to the
    `Collector`.
 
-Different instances of `Tracer` are independent of each other.  If an
-application wishes to reconfigure tracing at runtime, it can create another
-`Tracer` using the new configuration.
-
-[1]: https://datadog.github.io/dd-trace-cpp/datadog
+Different instances of `Tracer` are independent of each other. If an application wishes to
+reconfigure tracing at runtime, it can create another `Tracer` using the new configuration.

doc/decisions.md

@@ -1,39 +1,39 @@
 Here are some topics that were discussed during the design of this library.
 
 - Which version of C++ do we require?
+  - C++17
 - Which C core libraries do we produce binaries for?
-    - glibc
-    - musl
+  - glibc
+  - musl
 - Which build systems do we support?
-    - CMake
-    - Bazel
+  - CMake
+  - Bazel
 - Which unit testing framework?
-    - Catch2
-    - Google Test
-- Integration tests?
+  - Catch2
+  - Google Test
 - Error handling options:
-    - `std::variant<T, Error>`
-    - homebrew a `std::expected<T>`
-    - `throw Error(...)`
-    - `RCode do_thing(T& output)`
-    - `struct Result { Error error; T value; }`
+  - `std::variant<T, Error>`
+  - homebrew a `std::expected<T>`
+  - `throw Error(...)`
+  - `RCode do_thing(T& output)`
+  - `struct Result { Error error; T value; }`
 - Is a `Span` RAII with respect to start/finish?
-- When we begin calculating trace metrics within the tracer, we'll need to hit
-  a `/stats` HTTP endpoint.
-    - Does it live on the same thread as the `Collector`?
-    - Do we invent a library-specific `HTTPClient` interface?
+- When we begin calculating trace metrics within the tracer, we'll need to hit a `/stats` HTTP
+  endpoint.
+  - Does it live on the same thread as the `Collector`?
+  - Do we invent a library-specific `HTTPClient` interface?
 - Do we keep using cURL for the default `Collector`?
-    - In-tree C++ library instead?
+  - In-tree C++ library instead?
 - Naming conventions:
-    - `class TypeName;`
-    - `.member_function();`
-    - `free_function();`
-    - `f(int func_arg);`
-    - `int local_var;`
-    - `int private_member_;`
-    - `int public_member;`
-    - `enum Color { red, green, blue };`
-    - `which_one<TraceId, TraceID>`
+  - `class TypeName;`
+  - `.member_function();`
+  - `free_function();`
+  - `f(int func_arg);`
+  - `int local_var;`
+  - `int private_member_;`
+  - `int public_member;`
+  - `enum Color { red, green, blue };`
+  - `which_one<TraceId, TraceID>`
 - Can tracing be reconfigured at runtime?
 - Can multiple tracers share a collector?
 - Are rate limits per-tracer, per-process, or other?