Skip to content

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

@epage

Description

@epage
Contributor

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.

Activity

polarathene

polarathene commented on Oct 24, 2024

@polarathene
Collaborator

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:

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

epage commented on Oct 24, 2024

@epage
ContributorAuthor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @epage@polarathene

        Issue actions

          Docs don't make it obvious how the pieces connect together · Issue #591 · rust-cli/config-rs