Merge pull request #417 from maxmind/greg/eng-4241

Fix documentation grammar, types, signatures, and add missing docs

Author: horgh

.github/workflows/precious.yml

@@ -0,0 +1,24 @@
+name: precious
+
+on:
+  push:
+  pull_request:
+
+permissions: {}
+
+jobs:
+  precious:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup mise
+        uses: jdx/mise-action@6d1e696aa24c1aa1bcc1adea0212707c71ab78a8 # v3.6.1
+        with:
+          cache: true
+
+      - name: Run precious lint
+        run: precious lint --all

.precious.toml

@@ -0,0 +1,24 @@
+exclude = [
+    ".git",
+    "maxmind-db/**",
+    "t/libtap/**",
+    "t/maxmind-db/**",
+]
+
+[commands.clang-format]
+type = "both"
+cmd = ["clang-format", "-style=file"]
+lint-flags = ["--dry-run", "-Werror"]
+tidy-flags = ["-i"]
+path-args = "file"
+include = ["**/*.c", "**/*.h"]
+ok-exit-codes = 0
+
+[commands.prettier-markdown]
+type = "both"
+cmd = ["prettier", "--prose-wrap", "always", "--print-width", "80"]
+lint-flags = ["--check"]
+tidy-flags = ["--write"]
+path-args = "file"
+include = ["**/*.md"]
+ok-exit-codes = 0

Changes.md

@@ -3,17 +3,17 @@
 We release by uploading the tarball to GitHub and uploading Ubuntu PPAs.
 
 ## Creating the release tarball
+
 You may want to refer to the section about prerequisites.
 
-* Check whether there are any open issues to fix while you're doing this.
-* Update `Changes.md` to include specify the new version, today's date, and
-  list relevant changes. Commit this.
-* Create a new branch off of the latest `main` for the release.
-* Run `./dev-bin/release.sh` to update various files in the distro, our
-  GitHub pages, and creates a GitHub release with the tarball.
-* Check the release looks good on both GitHub and launchpad.net.
-* Make a pull request against `main` with the changes from the release
-  script.
+- Check whether there are any open issues to fix while you're doing this.
+- Update `Changes.md` to specify the new version, today's date, and list
+  relevant changes. Commit this.
+- Create a new branch off of the latest `main` for the release.
+- Run `./dev-bin/release.sh` to update various files in the distro, our GitHub
+  pages, and creates a GitHub release with the tarball.
+- Check the release looks good on both GitHub and launchpad.net.
+- Make a pull request against `main` with the changes from the release script.
 
 ## PPA
 
@@ -22,56 +22,53 @@ register a GPG key with that account. You also need to be added to the MaxMind
 team. Ask in the dev channel for someone to add you. See
 https://help.launchpad.net/Packaging/PPA for more details.
 
-The PPA release script is at `dev-bin/ppa-release.sh`. Running it should
-guide you though the release, although it may require some changes to run on
+The PPA release script is at `dev-bin/ppa-release.sh`. Running it should guide
+you though the release, although it may require some changes to run on
 configurations different than Greg's machine.
 
-Check whether any new Ubuntu versions need to be listed in this script
-before running it.
+Check whether any new Ubuntu versions need to be listed in this script before
+running it.
 
 You should run it from `main`.
 
 ## Homebrew (optional)
 
-Releasing to Homebrew is no longer required as the formulas are easily
-updated by the end-user using a built-in feature in the tool. These
-directions remain in case there is a more significant change to the
-build process that may require a non-trivial update to the formula or
-in the case where we want the Homebrew version updated promptly for
-some reason.
+Releasing to Homebrew is no longer required as the formulas are easily updated
+by the end-user using a built-in feature in the tool. These directions remain in
+case there is a more significant change to the build process that may require a
+non-trivial update to the formula or in the case where we want the Homebrew
+version updated promptly for some reason.
 
-* Go to https://github.com/Homebrew/homebrew-core/edit/master/Formula/libmaxminddb.rb
-* Edit the file to update the url and sha256. You can get the sha256 for the
+- Go to
+  https://github.com/Homebrew/homebrew-core/edit/master/Formula/libmaxminddb.rb
+- Edit the file to update the url and sha256. You can get the sha256 for the
   tarball with the `sha256sum` command line utility.
-* Make a commit with the summary `libmaxminddb <VERSION>`
-* Submit a PR with the changes you just made.
+- Make a commit with the summary `libmaxminddb <VERSION>`
+- Submit a PR with the changes you just made.
 
 # Prerequisites for releasing
 
-* Required packages (Ubuntu Artful): vim git-core dput build-essential
-  autoconf automake libtool git-buildpackage libfile-slurp-perl pandoc
-  dirmngr libfile-slurp-tiny-perl libdatetime-perl debhelper dh-autoreconf
+- Required packages (Ubuntu Artful): vim git-core dput build-essential autoconf
+  automake libtool git-buildpackage libfile-slurp-perl pandoc dirmngr
+  libfile-slurp-tiny-perl libdatetime-perl debhelper dh-autoreconf
   libipc-run3-perl libtest-output-perl devscripts
-* Install [gh](https://github.com/cli/cli/releases).
-* GitHub ssh key (e.g. in `~/.ssh/id_rsa`)
-* Git config (e.g. `~/.gitconfig`)
-* Import your GPG secret key (or create one if you don't have a suitable
-  one)
-  * `gpg --import /path/to/key`
-  * `gpg --edit-key KEYID` and trust it ultimately
-  * Ensure it shows with `gpg --list-secret-keys`
-* You need to be invited to the launchpad.net MaxMind organization on your
+- Install [gh](https://github.com/cli/cli/releases).
+- GitHub ssh key (e.g. in `~/.ssh/id_rsa`)
+- Git config (e.g. `~/.gitconfig`)
+- Import your GPG secret key (or create one if you don't have a suitable one)
+  - `gpg --import /path/to/key`
+  - `gpg --edit-key KEYID` and trust it ultimately
+  - Ensure it shows with `gpg --list-secret-keys`
+- You need to be invited to the launchpad.net MaxMind organization on your
   launchpad.net account.
-* You need your GPG key listed on your launchpad.net account
-  * You can add it in the web interface. It wants the output of
+- You need your GPG key listed on your launchpad.net account
+  - You can add it in the web interface. It wants the output of
     `gpg --fingerprint`.
-  * Part of the instructions involve having your key published on the
-    Ubuntu keyserver:
-    `gpg --keyserver keyserver.ubuntu.com --send-keys KEYID`
-  * You'll get an email with an encrypted payload that you need to decrypt
-    and follow the link to confirm it.
-* Ensure `dch` knows your name and email. Refer to its man page for how to
-  tell it this. One way is to set the `DEBFULLNAME` and `DEBEMAIL`
-  environment variables. These should match your GPG key's name and email
-  exactly. This is what gets used in the Debian changelog as well as
-  defines what GPG key to use.
+  - Part of the instructions involve having your key published on the Ubuntu
+    keyserver: `gpg --keyserver keyserver.ubuntu.com --send-keys KEYID`
+  - You'll get an email with an encrypted payload that you need to decrypt and
+    follow the link to confirm it.
+- Ensure `dch` knows your name and email. Refer to its man page for how to tell
+  it this. One way is to set the `DEBFULLNAME` and `DEBEMAIL` environment
+  variables. These should match your GPG key's name and email exactly. This is
+  what gets used in the Debian changelog as well as defines what GPG key to use.

README.dev.md

@@ -9,10 +9,10 @@ These tests are only meant to be run on GNU/Linux.
 Note that in `CFLAGS` and `CXXFLAGS`, any type of sanitizers can be added.
 
 - [AddressSanitizer](https://clang.llvm.org/docs/AddressSanitizer.html),
-    [ThreadSanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html),
-    [MemorySanitizer](https://clang.llvm.org/docs/MemorySanitizer.html),
-    [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html),
-    [LeakSanitizer](https://clang.llvm.org/docs/LeakSanitizer.html).
+  [ThreadSanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html),
+  [MemorySanitizer](https://clang.llvm.org/docs/MemorySanitizer.html),
+  [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html),
+  [LeakSanitizer](https://clang.llvm.org/docs/LeakSanitizer.html).
 
 ```shell
 $ export CC=clang
@@ -38,4 +38,5 @@ $ find ../t/maxmind-db/test-data/ -type f -size -4k -exec cp {} ./fuzz_mmdb_seed
 $ ./t/fuzz_mmdb fuzz_mmdb_seed/ fuzz_mmdb_seed_corpus/
 ```
 
-Here is more information about [LibFuzzer](https://llvm.org/docs/LibFuzzer.html).
+Here is more information about
+[LibFuzzer](https://llvm.org/docs/LibFuzzer.html).

README.fuzzing.md

@@ -6,8 +6,8 @@ designed to facilitate fast lookups of IP addresses while allowing for great
 flexibility in the type of data associated with an address.
 
 The MaxMind DB format is an open format. The spec is available at
-https://maxmind.github.io/MaxMind-DB/. This spec is licensed under the
-Creative Commons Attribution-ShareAlike 3.0 Unported License.
+https://maxmind.github.io/MaxMind-DB/. This spec is licensed under the Creative
+Commons Attribution-ShareAlike 3.0 Unported License.
 
 See https://dev.maxmind.com/ for more details about MaxMind's GeoIP2 products.
 
@@ -23,9 +23,9 @@ This library is licensed under the Apache License, Version 2.
 tarballs on the [Releases](https://github.com/maxmind/libmaxminddb/releases)
 page (e.g. `libmaxminddb-*.tar.gz`).
 
-This code is known to work with GCC 4.4+ and clang 3.2+. It should also work
-on other compilers that supports C99, POSIX.1-2001, and the `-fms-extensions
-flag` (or equivalent). The latter is needed to allow an anonymous union in a
+This code is known to work with GCC 4.4+ and clang 3.2+. It should also work on
+other compilers that support C99, POSIX.1-2001, and the `-fms-extensions flag`
+(or equivalent). The latter is needed to allow an anonymous union in a
 structure.
 
 To install this code, run the following commands:
@@ -56,16 +56,16 @@ ldconfig
 
 ## From a GitHub "Source Code" Archive / Git Repo Clone (Achtung!)
 
-**NOTE:** These instructions are for installation from the GitHub "Source
-Code" archives also available on the
+**NOTE:** These instructions are for installation from the GitHub "Source Code"
+archives also available on the
 [Releases](https://github.com/maxmind/libmaxminddb/releases) page (e.g.
-`X.Y.Z.zip` or `X.Y.Z.tar.gz`), as well as installation directly from a clone
-of the [Git repo](https://github.com/maxmind/libmaxminddb). Installation from
-these sources are possible but will present challenges to users not
-comfortable with manual dependency resolution.
+`X.Y.Z.zip` or `X.Y.Z.tar.gz`), as well as installation directly from a clone of
+the [Git repo](https://github.com/maxmind/libmaxminddb). Installation from these
+sources is possible but will present challenges to users not comfortable with
+manual dependency resolution.
 
-You will need `automake`, `autoconf`, and `libtool` installed
-in addition to `make` and a compiler.
+You will need `automake`, `autoconf`, and `libtool` installed in addition to
+`make` and a compiler.
 
 You can clone this repository and build it by running:
 
@@ -74,8 +74,8 @@ git clone --recursive https://github.com/maxmind/libmaxminddb
 ```
 
 After cloning, run `./bootstrap` from the `libmaxminddb` directory and then
-follow the instructions for installing from a named release tarball as
-described above.
+follow the instructions for installing from a named release tarball as described
+above.
 
 ## Using CMake
 
@@ -91,8 +91,8 @@ ctest -V .
 cmake --build . --target install
 ```
 
-When building with Visual Studio, you may build a multithreaded (MT/MTd)
-runtime library, using the `MSVC_STATIC_RUNTIME` setting:
+When building with Visual Studio, you may build a multithreaded (MT/MTd) runtime
+library, using the `MSVC_STATIC_RUNTIME` setting:
 
 ```bash
 cmake -DMSVC_STATIC_RUNTIME=ON -DBUILD_SHARED_LIBS=OFF ..
@@ -106,8 +106,8 @@ cmake --build . --target uninstall
 
 ## On Ubuntu via PPA
 
-MaxMind provides a PPA for recent version of Ubuntu. To add the PPA to your
-APT sources, run:
+MaxMind provides a PPA for recent version of Ubuntu. To add the PPA to your APT
+sources, run:
 
 ```bash
 sudo add-apt-repository ppa:maxmind/ppa
@@ -136,8 +136,8 @@ sudo port install libmaxminddb
 
 # Requirements
 
-libmaxminddb requires a minimum of POSIX.1-2001 support. If not specified
-at compilation time, it defaults to requesting POSIX.1-2008 support.
+libmaxminddb requires a minimum of POSIX.1-2001 support. If not specified at
+compilation time, it defaults to requesting POSIX.1-2008 support.
 
 # Bug Reports
 
@@ -152,14 +152,13 @@ Use `make safedist` to check the resulting tarball.
 
 Copyright 2013-2025 MaxMind, Inc.
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at
 
     https://www.apache.org/licenses/LICENSE-2.0
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.