Docs don't make it obvious how the pieces connect together

[epage]

There is no top-level example, core types are re-exported, rather than inline in the top-level docs, and many items are in the top-level without being clear when to use them without digging into all of the documentation.

[polarathene]

I remember collaborating with a contributor about a year ago with an example for implementing custom formats, that was not documented well.

Adding here as context / reference if helpful: #479 (comment)

---

Similarly for the library itself, I had some PRs that may be helpful towards how support for adding formats looked:

• feat: Added Gura support #467
• feat: Add Dhall support #466
• refactor: ini format parser #470
• Ron has still not released 0.9 yet: chore: Upgrade to ron to 0.9 #476

Related was a refactor to simplify format support which may have been easier to document and introduced more consistency vs each format doing roughly the same slightly differently. That included some changes to favor serde crates though, notably for YAML which did not age well 😓

HJSON could take a similar approach (detailed config-rs history), and I recall my local copy of config-rs having some other formats that were quite simple with the refactor to add.

[epage]

I'm even thinking on a more basic level. When I see docs.rs/<crate>, how do I tell what pieces are relevant to what I'm trying to accomplish? This is more about having things like

• top-level example
• intra-doc links

etc

What you described would likely better fall under #593.