Sanitize Google descriptions so ExDoc docs build clean#7
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
mix hex.publishemitted ExDoc warnings while generating docs forgoogly_document_ai. Two kinds, both from Google's discovery descriptions being emitted verbatim into@moduledoc/@doc: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 (typeinstead ofactive_schema_version).[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/2rewrites root-relative](/foo)targets to absolute URLs viaURI.merge/2, resolving against the API's own documentation host (documentationLink), threaded in asdocs_link(token). This matters becausegooglytargets any Google API and hosts differ — Cloud Storage lives underdevelopers.google.com/storage/docs/json_api/, while Vision/DocumentAI are undercloud.google.com. Absolute and protocol-relative (//host) targets are left alone.close_dangling_inline_code/1appends 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 staysreq+jasononly.docs_link/1is now public and shares a@default_docs_linkfallback withdoc/3.Testing
doc/3unit tests (unterminated code span; balanced backticks untouched; root-relative link against the default host and against an explicitdevelopers.google.combase; absolute/protocol-relative untouched). Full suite: 65 passed.cloud.google.com), so no committed client changed beyond the original one-line link fix.cd clients/googly_document_ai && mix docs→ zero 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.