[smilliken]

The best kind of documentation is the kind you can trust is accurate. Type defs wouldn't be close to as useful if you didn't really trust them. Similarly, doctests are some of the most useful documentation because you can be sure they are accurate.

[zbentley]

The best docs are the ones you can trust are accurate. The second best docs are ones that you can programmatically validate. The worst docs are the ones that can’t be validated without lots of specialized effort.

Python’s type hints are in the second category.

[btown]

I’d almost switch the order here! In a world with agentic coding agents that can constantly check for type errors from the language server powering the errors/warnings in your IDE, and reconcile them against prose in docstrings… types you can programmatically validate are incredibly valuable.

[seniorsassycat]

Do you have an example of the first?

[zbentley]

When I wrote that, I was thinking about typed, compiled languages' documentation generated by the compiler at build time. Assuming that version drift ("D'oh, I was reading the docs for v1.2.3 but running v4.5.6") is user error and not a docs-trustworthiness issue, that'd qualify.

But now that I'm coming back to it, I think that this might be a larger category than I first envisioned, including projects whose build/release processes very reliably include the generation+validation+publication of updated docs. That doesn't imply a specific language or release automation, just a strong track record of doc-accuracy linked to releases.

In other words, if a user can validate/regenerate the docs for a project, that gets it 9/10 points. The remaining point is the squishier "the first party docs are always available and well-validated for accuracy" stuff.

[zbentley]

Another example of extremely far towards the "accurate and trustworthy" end of the spectrum: asking a running webservice for the e.g. Swagger/OpenAPI schema that it is currently using to serve requests. If you can trust that those docs are produced (on request or cached at deployment time) by the same backend application instances serving other requests, you'd have pretty high assurance.

Nobody does that, though. Instead they all auto-publish their OpenAPI schemas through rickety-ass, fail-soft build systems to flaky, unmonitored CDNs. Then they get mad at users who tell them when their API docs don't match their running APIs.

[ItsHarper]

Languages with strong static type systems

[LudwigNagasena]

Is there a mainstream language where you can’t arbitrarily cast a variable to any other type?