Skip to content

Sanitize Google descriptions so ExDoc docs build clean#7

Merged
mhsdef merged 1 commit into
mainfrom
fix/exdoc-doc-warnings
Jul 2, 2026
Merged

Sanitize Google descriptions so ExDoc docs build clean#7
mhsdef merged 1 commit into
mainfrom
fix/exdoc-doc-warnings

Conversation

@mhsdef

@mhsdef mhsdef commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

What

mix hex.publish emitted ExDoc warnings while generating docs for googly_document_ai. Two kinds, both from Google's discovery descriptions being emitted verbatim into @moduledoc/@doc:

  1. "Closing unclosed backquotes" — a description opens an inline code span it never closes (Format is `projects/.../{schema_version}). EarmarkParser counts backticks across the whole moduledoc, finds an odd total, and reports it at end-of-input — which is why the warning fingered the wrong field (type instead of active_schema_version).
  2. "references file ... does not exist"[regional and multi-regional support](/document-ai/docs/regions); ExDoc resolves any /… target as a local file.

How

Both are fixed in Renderer.doc/3 — the single place every description flows through:

  • normalize_markdown_links/2 rewrites root-relative ](/foo) targets to absolute URLs via URI.merge/2, resolving against the API's own documentation host (documentationLink), threaded in as docs_link(token). This matters because googly targets any Google API and hosts differ — Cloud Storage lives under developers.google.com/storage/docs/json_api/, while Vision/DocumentAI are under cloud.google.com. Absolute and protocol-relative (//host) targets are left alone.
  • close_dangling_inline_code/1 appends a closing backtick when a description's backtick count is odd. This is deliberately a small upstream-prose repair, not real Markdown parsing — pulling in EarmarkParser just to fix Google's typos isn't worth it, and the generated client runtime stays req + jason only.

docs_link/1 is now public and shares a @default_docs_link fallback with doc/3.

Testing

  • Added 5 doc/3 unit tests (unterminated code span; balanced backticks untouched; root-relative link against the default host and against an explicit developers.google.com base; absolute/protocol-relative untouched). Full suite: 65 passed.
  • Regenerated all clients — output is byte-identical to before (DocumentAI's host is cloud.google.com), so no committed client changed beyond the original one-line link fix.
  • cd clients/googly_document_ai && mix docszero warnings; mix compile --force --warnings-as-errors → clean (340 files).

Notes

Per the golden rule, the fix lives in the generator/templates (never hand-edited generated code); the 4 regenerated DocumentAI model files are committed output.

Google's discovery descriptions are emitted verbatim into @moduledoc/@doc
via Renderer.doc/*, and two kinds of malformed Markdown made mix hex.publish
warn during doc generation:

- Unterminated inline code spans (e.g. `Format is `projects/.../{v}`) →
  EarmarkParser "Closing unclosed backquotes".
- Root-relative links (e.g. [regions](/document-ai/docs/regions)) → ExDoc
  resolves /... as a local file and warns it doesn't exist.

Fix both in doc/3 (the one place all description text flows through):
- normalize_markdown_links/2 resolves ](/foo) against the API's own
  documentation host via URI.merge/2 — threaded in as docs_link(token), since
  googly targets any Google API and hosts differ (Cloud Storage lives under
  developers.google.com, most others under cloud.google.com).
- close_dangling_inline_code/1 appends a closing backtick when a description's
  count is odd. This is upstream-prose repair, not Markdown parsing — not worth
  a parser dependency (the client runtime stays req + jason only).

docs_link(token) is now public and shares a @default_docs_link fallback with
doc/3. Regenerated all clients: output is byte-identical (DocumentAI's host is
cloud.google.com), so no committed client changed beyond the original fix.
mix docs builds with zero warnings; client compiles warnings-as-errors.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mhsdef mhsdef merged commit b8e865c into main Jul 2, 2026
8 checks passed
mhsdef added a commit that referenced this pull request Jul 3, 2026
Bumps googly_cloud_storage, googly_cloud_vision, and googly_document_ai
to 0.1.2 via `mix googly.release`, and fills in the 0.1.2 changelog
entries covering the changes since 0.1.1 (#7, #8, #9).

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant