Skip to content

Fix docs/implementation consistency issues; convert naming-only $id to title - #188

Open
wol-soft wants to merge 1 commit into
masterfrom
claude/docs-schema-consistency-kq0qwe
Open

Fix docs/implementation consistency issues; convert naming-only $id to title#188
wol-soft wants to merge 1 commit into
masterfrom
claude/docs-schema-consistency-kq0qwe

Conversation

@wol-soft

@wol-soft wol-soft commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Summary

Reviewed docs/source and README.md for divergence from the actual implementation, and for $id usage where title should be used instead.

  • Converted $id usages that only existed to name example classes into title, matching the real class-naming priority (title outranks $id, verified against ClassNameGenerator). generic/references.rst keeps $id since it specifically documents id-based $ref resolution — its root-level values were changed to realistic URIs instead.
  • Fixed stale API references: new Generator()new ModelGenerator(), setter return types shown as a concrete class instead of static, getRawModelDataInput() (doesn't exist anywhere in the codebase) → meta()->rawInput(), NestedObjectException's wrong namespace (GenericObject).
  • Fixed invalid JSON in several example schemas (missing/trailing commas) and several wrong setter parameter names that didn't match their actual property (verified against the Model.phptpl naming rule).
  • Fixed broken/wrong doc links and a duplicated toctree entry for customDraft.
  • Corrected generic/meta.rst's outdated "ID" naming explanation (it predated title support) and added the missing $anchor step to complexTypes/object.rst's naming priority list.
  • Documented minContains/maxContains (fully implemented, previously undocumented anywhere), the Draft_2019_09/Draft_2020_12 draft classes (existing, tested, but absent from the docs' draft table), and the enum exception message truncation behavior for enums with more than 8 values.
  • Verified exception message wording, getter names, and behavior claims against the sibling php-json-schema-model-generator-production repo where docs quote its classes directly.

Test plan

  • Extracted and validated every JSON code block across docs/source with a script; all now parse as valid JSON (excluding intentionally-abbreviated fragments using ...)
  • Checked every relative doc link (file + anchor) against actual files/headers; no remaining broken links
  • Cross-checked exception messages, getter names, and class namespaces against src/ and the production repo
  • docs/ not rendered with Sphinx in this session — recommend a docs build to catch any RST syntax issues before merge

🤖 Generated with Claude Code

https://claude.ai/code/session_01TcoPe6sLfqkEqNEBoV2Wgi


Generated by Claude Code

…d to title

Reviews docs/source and README for divergence from the actual implementation:

- Converts $id usages that only existed to name example classes into title,
  matching the real class-naming priority (title outranks $id). generic/references.rst
  keeps $id since it specifically documents id-based $ref resolution, with root
  values changed to realistic URIs.
- Fixes stale API references: new Generator() -> new ModelGenerator(), setter
  return types shown as concrete classes instead of static, getRawModelDataInput()
  which doesn't exist -> meta()->rawInput(), NestedObjectException's wrong namespace.
- Fixes invalid JSON in several example schemas (missing/trailing commas) and
  several wrong setter parameter names that didn't match their property.
- Fixes broken/wrong doc links and a duplicated toctree entry.
- Corrects generic/meta.rst's outdated "ID" naming explanation and adds the
  missing $anchor step to complexTypes/object.rst's naming priority list.
- Documents minContains/maxContains (implemented but previously undocumented),
  the Draft 2019-09/2020-12 draft classes, and the enum exception message
  truncation behavior for large enums.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TcoPe6sLfqkEqNEBoV2Wgi
@coveralls

Copy link
Copy Markdown

Coverage Report for CI Build 31333517295

Coverage remained the same at 98.76%

Details

  • Coverage remained the same as the base build.
  • Patch coverage: No coverable lines changed in this PR.
  • No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.


Coverage Stats

Coverage Status
Relevant Lines: 7341
Covered Lines: 7250
Line Coverage: 98.76%
Coverage Strength: 1664.24 hits per line

💛 - Coveralls

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.

3 participants