Message-ID: <gh-pgjdbc-pgjdbc-4077@github.com>
From: "vlsi (@vlsi)" <noreply+vlsi@github.com>
To: "pgjdbc/pgjdbc" <noreply+pgjdbc-pgjdbc@github.com>
Date: Mon, 18 May 2026 08:58:32 +0000
Subject: [pgjdbc/pgjdbc] PR #4077: pgjdbc: introduce @PgApi / @PgTags / @PgPropertyType annotations on PGProperty
List-Id: <gh-pgjdbc-pgjdbc.github.com>
X-GitHub-Author-Id: 213894
X-GitHub-Author-Login: vlsi
X-GitHub-Issue: 4077
X-GitHub-Labels: documentation
X-GitHub-Repo: pgjdbc/pgjdbc
X-GitHub-State: open
X-GitHub-Type: pull_request
X-GitHub-Url: https://github.com/pgjdbc/pgjdbc/pull/4077
Content-Type: text/plain; charset=utf-8

Adds three CLASS-retained annotations in org.postgresql.annotations and applies them to all 87 PGProperty values. The annotations are the contract a documentation generator can read via ASM bytecode inspection — without exposing the data at runtime.

The annotations are is used in https://github.com/pgjdbc/pgjdbc/pull/4075 to implement https://github.com/pgjdbc/pgjdbc/issues/1687

---

The annotations are designed after https://github.com/apiguardian-team/apiguardian with several changes:
* The annotations are renamed to avoid third-party dependencies
* I've added special fields to track "available since, deprecated in, hidden in", see https://github.com/apiguardian-team/apiguardian/issues/207
* I've added `status=HIDDEN` so we can hide certain members at the bytecode later, see https://github.com/apiguardian-team/apiguardian/issues/208

---

```
  PgApi(status, introducedIn, deprecatedIn, hiddenIn)
    Lifecycle status (STABLE / EXPERIMENTAL / MAINTAINED / INTERNAL /
    DEPRECATED / HIDDEN) plus three orthogonal version axes so docs can
    render "Available since X.Y; deprecated in Y.Z; hidden in Z.W"
    without losing any.

  PgTags(Tag[]) — topical buckets (SSL, AUTHENTICATION, FETCH, TIMEOUT,
    NETWORK, KERBEROS_GSS, ...) plus the OPERATIONS secondary tag for
    properties tuned at deployment time. Drives section-specific
    sub-tables in the docs.

  PgPropertyType(Kind) — semantic data type, with unit-bearing variants
    (DURATION_SECONDS / DURATION_MILLIS, SIZE_BYTES / SIZE_EXPRESSION).
    Surfaces "is this number seconds or milliseconds?" — a long-standing
    pgjdbc foot-gun.
```

All annotations use `@Retention(CLASS)` so they are visible to bytecode readers but not exposed at runtime. Pg-prefixed names avoid collisions with widely-used annotation libraries (`org.apiguardian.api.API` ships with JUnit Jupiter), so a user typing `@Pg...` in their IDE sees only pgjdbc annotations.

Each DEPRECATED `@PgApi` sits alongside the standard JDK `@Deprecated` so that both bytecode readers and the compiler / IDE see the deprecation.