glideapps / glideapps/quicktype

[FEATURE]: document options

Open
#3,117 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
13.9k
Forks
1.2k
Avg merge
8h 53m
Merged PRs (30d)
369

Description

What are the options?

The app doesn't say how each option maps to options in the CLI or in javascript. It's just sort of "there" and you have to trust that those options are somehow mapped to something. Especially on the CLI you have to just guess what might be right. In Javascript too. In Typescript at least you get some kind of insight, but each option doesn't map neatly with the label present in the app. And that's basically the only lead.

It'd be helpful to document them.

Yes, I've looked through the documentation. And it's great, but not great enough 🙂

> The argument to quicktype is a complex object with many optional properties. [Explore its definition](https://github.com/quicktype/quicktype/blob/master/packages/quicktype-core/src/Run.ts#L637) to understand what options are allowed.

That's a link to the options "documentation" directing the reader to the code, "here, explore it yourself". Except that link doesn't actually go to the shape of the options, just some random location in some seemingly random source file. So the idea was sound, but it probably wasn't updated. I wonder what takes more effort: updating documentation every once in a blue moon when the options change, or updating a link to a source file every time that file changes.

There's also a dead link to something I was hoping could help:

> Blog post with an older example: http://blog.quicktype.io/customizing-quicktype/

What ever happened to that blog?

Documentation just needs some love.

Contributor guide

Open the contributing guide

Research direction

Start with the options documentation and the linked Run.ts location around line 637, then compare the app labels with the CLI, JavaScript, and TypeScript option definitions. Document how each option maps across interfaces, verify the link points to the current options shape, and resolve or remove the dead blog-post reference.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
cli, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.