Little fixes and improvements in documentation (#279)

Author: xlamorlette-datadog

.github/CODEOWNERS

@@ -2,4 +2,4 @@
 # https://help.github.com/en/articles/about-code-owners
 
 # Default owners, overridden by file/directory specific owners below
-* @DataDog/dd-trace-cpp
+* @DataDog/dd-trace-cpp @DataDog/cpp-reviewers

.gitignore

@@ -1,14 +1,13 @@
-/bazel-*
-/.build/
-/build/
-/build-*/
-/.coverage/
-build/
-
-dist/
-out/
-MODULE.bazel.lock
-.vscode
+.build/
 .cache/
+.coverage/
 .cursor/
 .DS_Store
+.install/
+.vscode
+bazel-*
+build-*/
+build/
+dist/
+MODULE.bazel.lock
+out/

Dockerfile

@@ -1,5 +1,4 @@
-# This is the image used to build and test the library in CircleCI.
-# See .circleci/ for more information.
+# This is the image used to build and test the library in CI.
 
 from ubuntu:22.04
 
@@ -37,4 +36,3 @@ copy bin/install-lcov /tmp/install-lcov
 run chmod +x /tmp/install-lcov && /tmp/install-lcov && rm /tmp/install-lcov
 
 run curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/main/install.sh | bash
-

README.md

@@ -52,12 +52,12 @@ The library has been tested and is compatible on the following CPU architecture,
 ### Requirements
 `dd-trace-cpp` requires a [supported](#platform-support) C++17 compiler.
 
-A recent version of CMake is required (`3.24`), which might not be in your
+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.
+for a recent CMake, on Linux.
 
 ### Building
-Build this library from source using [CMake][1].
+Build this library from source using [CMake](https://cmake.org).
 
 ```shell
 git clone 'https://github.com/datadog/dd-trace-cpp'
@@ -66,7 +66,7 @@ cmake -B build .
 cmake --build build -j
 ```
 
-By default CMake will generate both static and shared libraries. To build either on of them use
+By default CMake will generate both static and shared libraries. To build only one of them use
 either `BUILD_SHARED_LIBS` or `BUILD_STATIC_LIBS`. Example:
 
 ```shell
@@ -75,14 +75,11 @@ 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.
+(`/usr/local/[…]`), or to a specified installation prefix. Example:
 
 ```shell
-cmake --install
-
-# Here is how to install dd-trace-cpp into `.install/` within the source
-# repository.
-# cmake --install build --prefix=.install
+# Install dd-trace-cpp into `.install/` within the source repository.
+cmake --install build --prefix=.install
 ```
 
 ### Optional: Linking to the shared library
@@ -110,18 +107,14 @@ Pass `-DDD_TRACE_BUILD_TESTING=1` to `cmake` to include the unit tests in the bu
 
 The resulting unit test executable is `test/tests` within the build directory.
 ```shell
-cmake -Bbuild -DDD_TRACE_BUILD_TESTING=1 ..
+cmake -B build -DDD_TRACE_BUILD_TESTING=1 .
 cmake --build build -j
 ./build/test/tests
 ```
 
 Alternatively, [bin/test](bin/test) is provided for convenience.
 
-Code coverage reports are available [here][2].
-
 Contributing
 ------------
-See the [contributing guidelines](CONTRIBUTING.md) and the [maintainer docs](doc/maintainers.md) for information on the overall structure of the repository.
-
-[1]: https://cmake.org/
-[2]: https://datadog.github.io/dd-trace-cpp-coverage
+See the [contributing guidelines](CONTRIBUTING.md) and the [maintainer docs](doc/maintainers.md)
+for information on the overall structure of the repository.

bin/README.md

@@ -2,20 +2,21 @@ Scripts
 =======
 This directory contains scripts that are useful during development.
 
-- [bazel-build](bazel-build) builds the library using [Bazel][1] via [bazelisk][2].
+- [bazel-build](bazel-build) builds the library using
+  [Bazel](https://bazel.build) via [bazelisk](https://github.com/bazelbuild/bazelisk).
 - [benchmark](benchmark) builds the library and its [benchmark](../benchmark),
   and runs the benchmark.
 - [check](check) performs some of the checks that [continuous
-  integration](../.circleci) performs. It's convenient to run this script before
-  pushing changes.
+  integration](../github/workflows) performs. It's convenient to run this script
+  before pushing changes.
 - [check-format](check-format) verifies that the source code is formatted as
   [format](format) prefers.
 - [check-version](check-version) accepts a version string as a command line
   argument (e.g. "v1.2.3") and checks whether the version within the source code
   matches. This is a good check to perform before publishing a source release.
-- [cmake-build](cmake-build) builds the library using [CMake][3].
+- [cmake-build](cmake-build) builds the library using [CMake](https://cmake.org).
 - [format](format) formats all of the C++ source code using
-  [clang-format-14][4].
+  [clang-format-14]( https://releases.llvm.org/14.0.0/tools/clang/docs/ClangFormat.html).
 - [hasher-example](hasher-example) builds the library, including the [command
   line example](../examples/hasher) program, and then runs the example.
 - [http-server-example](http-server-example) runs the docker compose based [HTTP
@@ -33,8 +34,3 @@ This directory contains scripts that are useful during development.
   `CXX` environment variables based on its first argument, which is either "gnu"
   (to use the gcc/g++ toolchain) or "llvm" (to use the clang/clang++ toolchain).
   For example: `with-toolchain llvm cmake -DDD_TRACE_BUILD_TESTING=1 ..`.
-
-[1]: https://bazel.build/
-[2]: https://github.com/bazelbuild/bazelisk
-[3]: https://cmake.org/
-[4]: https://releases.llvm.org/14.0.0/tools/clang/docs/ClangFormat.html

bin/check

@@ -1,6 +1,6 @@
 #!/bin/sh
 
-# Run some of the checks that are performed by CircleCI.
+# Run some of the checks that are performed by the CI.
 # This is convenient to run before committing.
 
 set -e

bin/format

@@ -33,6 +33,11 @@ if ! >/dev/null command -v docker; then
     exit 1
 fi
 
+if ! docker info >/dev/null 2>&1; then
+    >&2 echo "Docker is not running. Please start Docker."
+    exit 1
+fi
+
 # If they haven't downloaded the clang docker image before, then prompt the
 # user before telling docker to download it (it's large).
 image=silkeh/clang:$version
@@ -62,8 +67,10 @@ docker_clang_format() {
     # shellcheck disable=SC2086
     find_sources | while IFS= read -r arg; do
         process_arg "$arg"
+    # The --platform option forces linux/amd64 because silkeh/clang:14 is only available on this platform.
     done | xargs -0 \
       docker run \
+      --platform linux/amd64 \
       --interactive \
       --rm \
       --volume /etc/passwd:/etc/passwd:ro \

doc/maintainers.md

@@ -630,28 +630,6 @@ approaches:
 - Add a `Logger::log_debug` function that optionally prints fine-grained tracing
   information to the log, in violation of constraint (1).
 
-Operations
-----------
-TODO
-
-### Testing
-TODO
-
-### Code Coverage
-TODO
-
-### Benchmarks
-TODO
-
-### Continuous Integration
-TODO
-
-### Releases
-TODO
-
-### Support
-TODO
-
 [1]: https://github.com/DataDog/dd-opentracing-cpp
 [2]: https://github.com/open-telemetry/opentelemetry-cpp
 [3]: ../include/datadog/span.h

examples/README.md

@@ -3,6 +3,8 @@ Example Usage
 This directory contains two example projects that illustrate how dd-trace-cpp
 can be used to add Datadog tracing to a C++ application.
 
+- [baggage](baggage) demonstrates how to parse and validate baggage header
+  strings.
 - [hasher](hasher) is a command-line tool that creates a complete trace
   involving only one service.
 - [http-server](http-server) is an ensemble of services, including two C++