Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[types] Add JSDoc based on website docs #436

Merged
merged 10 commits into from
Feb 18, 2024

Conversation

MysteryBlokHed
Copy link
Member

@MysteryBlokHed MysteryBlokHed commented Feb 14, 2024

Related to #424

This is a work-in-progress PR to add documentation from the website to the types. This will not only allow for better developer experience by providing more informative in-editor documentation, but will also allow the docs to be auto-generated with a tool like TypeDoc in the future.

I've started by adding docs for the Hooks and ColorSpace classes, but docs for other classes/functions/properties should be added too.

If there are any classes or functions in particular that anyone thinks should have documentation brought over from the website, I'm open to suggestions. Some things seem relatively self-explanatory with their types, so I don't think that every method and property needs to include super-detailed docs.

Note: In the toGamut.d.ts file, I did actually modify the types themselves a bit in order to make them more accurate, and to make it easier to access the types for the function's options.

Copy link

netlify bot commented Feb 14, 2024

Deploy Preview for colorjs ready!

Name Link
🔨 Latest commit 5bc5c01
🔍 Latest deploy log https://app.netlify.com/sites/colorjs/deploys/65d249a27127dd0008cc8b52
😎 Deploy Preview https://deploy-preview-436--colorjs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@MysteryBlokHed
Copy link
Member Author

While not in the website, this could probably use some documentation for each property:

export interface Format {
type?: string | undefined;
name?: string | undefined;
id?: string | undefined;
coords?: string[] | undefined;
coordGrammar?: (string & { range?: [number, number] })[] | undefined;
serializeCoords?:
| ((coords: Coords, precision: number) => [string, string, string])
| undefined;
toGamut?: boolean | undefined;
commas?: boolean | undefined;
lastAlpha?: boolean | undefined;
noAlpha?: boolean | undefined;
test?: ((str: string) => boolean) | undefined;
parse?: ((str: string) => ColorConstructor) | undefined;
serialize?: ((coords: Coords, alpha: number, opts?: Record<string, any>) => string) | undefined;
}
export interface CoordMeta {
name?: string | undefined;
type?: string | undefined;
range?: [number, number] | undefined;
refRange?: [number, number] | undefined;
}

@MysteryBlokHed

This comment was marked as resolved.

Docs were based on the website and the JSDoc from the JavaScript files.
Some types were actually inaccurate (or could be made a bit more
specific), which I fixed.
Most other functions with more than a few options have their own
interfaces for options, so IMO it makes sense that that should follow
for this function as well.
@MysteryBlokHed MysteryBlokHed marked this pull request as ready for review February 17, 2024 00:06
Copy link
Member

@jgerigmeyer jgerigmeyer left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, thanks @MysteryBlokHed!

types/src/space.d.ts Show resolved Hide resolved
types/src/toGamut.d.ts Show resolved Hide resolved
types/src/toGamut.d.ts Outdated Show resolved Hide resolved
@MysteryBlokHed MysteryBlokHed merged commit 9c3c65b into color-js:main Feb 18, 2024
4 checks passed
@MysteryBlokHed MysteryBlokHed deleted the types/jsdoc-from-site branch February 18, 2024 23:29
@MysteryBlokHed
Copy link
Member Author

Oops, it looks like there's a formatting problem that made CI fail. I'll open a new PR to fix that.

jgerigmeyer added a commit that referenced this pull request Feb 19, 2024
* main:
  [ci] Update lint rules for PR's (#444)
  Parse both dashed-ident and ident versions, and add missing dashed-idents to color spaces. (#439)
  [types] Fix formatting in `toGamut.d.ts` (#445)
  [types] Add JSDoc based on website docs (#436)
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