Fail CI when a public API object is not documented

.changelog/79.added

@@ -0,0 +1 @@
+Add a `docstring-check` CI job that fails a pull request which adds an undocumented public API object

.github/workflows/misc.yml

@@ -279,6 +279,29 @@ jobs:
       - name: Run tests
         run: uvx --with tox-uv tox -e public-symbols-check
 
+  docstring-check:
+    name: docstring-check
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    if: |
+      !contains(github.event.pull_request.labels.*.name, 'Approve Docstring check')
+    steps:
+      - name: Checkout repo @ SHA - ${{ github.sha }}
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+
+      - name: Run tests
+        run: uvx --with tox-uv tox -e docstring-check
+
   shellcheck:
     name: shellcheck
     runs-on: ubuntu-latest

.github/workflows/templates/misc.yml.j2

@@ -45,6 +45,10 @@ jobs:
       !contains(github.event.pull_request.labels.*.name, 'Approve Public API check')
       && github.actor != 'otelbot[bot]' && github.event_name == 'pull_request'
     {%- endif %}
+    {%- if job_data == "docstring-check" %}
+    if: |
+      !contains(github.event.pull_request.labels.*.name, 'Approve Docstring check')
+    {%- endif %}
     {%- if job_data == "docs" %}
     if: |
       github.event_name == 'merge_group' ||

CONTRIBUTING.md

@@ -69,6 +69,7 @@ You can run `tox` with the following arguments:
 - `tox -e ruff` to run ruff linter and formatter checks against the entire codebase
 - `tox -e typecheck` to run pyright against entire code base.
 - `tox -e public-symbols-check` to run public_symbols_checker.py.
+- `tox -e docstring-check` to run docstring_checker.py.
 - `tox -e docker-tests-{otlpexporter,opencensus}` to run tests in both or either one location.
 - `tox -e tracecontext` to run integration tests for tracecontext.
 - `tox -e precommit` to run all `pre-commit` actions
@@ -148,6 +149,26 @@ behind this is that every PR that adds/removes public symbols fails in CI, forci
 If after checking them, it is considered that they are indeed necessary, the PR will be labeled with `Approve Public API check` so that this check is not
 run.
 
+### Docstrings
+
+Every public symbol needs a docstring, every parameter of a public function or method needs an entry
+in an `Args:` section, and every public function or method whose return annotation is not `None`
+needs a `Returns:` or `Yields:` section. Constructor parameters are documented on the class
+docstring rather than on `__init__`, because `docs/conf.py` does not set `special-members`, so an
+`__init__` docstring is never rendered in the API reference.
+
+Run `tox -e docstring-check` to list every public symbol that does not meet those requirements.
+The check is absolute: it reports every gap in the public API, not only the gaps your PR adds, so a
+PR that adds an undocumented symbol fails and so does a PR that changes nothing while an existing
+symbol stays undocumented.
+
+Run `tox -e docstring-check -- --against main` to see only the gaps your working tree has and that
+`main` does not. That narrows a long report down to your own share of it. It is a reading aid; the
+check that gates CI is the absolute run.
+
+If a gap is deliberate, the PR will be labeled with `Approve Docstring check` so that this check is
+not run.
+
 Also, we try to keep our console output as clean as possible. Most of the time this means catching expected log messages in the test cases:
 
 ``` python