prosemirror/prosemirror-state
1
0
Fork 0
Code Pull requests Activity

WIP: chore: Use JSDocs #24

Closed
onx2 wants to merge 2 commits from patch-1 into master
pull from: patch-1
merge into: prosemirror:master
Conversation 6 Commits 2 Files changed 1 +56 -28
onx2 commented 2024-08-15 06:48:11 +02:00 (Migrated from github.com)
Copy link

Using JSDocs makes for a nicer IDE experience when hovering over symbols. Also it contains a @throws keyword that highlights which methods should be wrapped in a try/catch when used in a production application to prevent hard crashes.

If this is okay to do, I'll update everything else to include additional JSDoc info.

Using JSDocs makes for a nicer IDE experience when hovering over symbols. Also it contains a `@throws` keyword that highlights which methods should be wrapped in a `try/catch` when used in a production application to prevent hard crashes. If this is okay to do, I'll update everything else to include additional JSDoc info.
onx2 (Migrated from github.com) reviewed 2024-08-15 06:52:07 +02:00
src/state.ts
@ -234,0 +254,4 @@
* @param {Object} config - The configuration object for deserialization.
* @param {Schema} config.schema - The schema to use. (Required)
* @param {readonly Plugin[]} [config.plugins] - The set of active plugins. (Optional)
* @param {any} json - The JSON representation of the state.
onx2 (Migrated from github.com) commented 2024-08-15 06:52:07 +02:00
Copy link

This type of JSDoc could be updated to have a link to the Typescript Type and also be extended to show properties within the object -- though a bit redundant with TS.

This type of JSDoc could be updated to have a link to the Typescript Type and also be extended to show properties within the object -- though a bit redundant with TS.
marijnh commented 2024-08-15 17:37:14 +02:00 (Migrated from github.com)
Copy link

No, this is not something we're going to do. The dist/ files do provide JSDoc commens so that TypeScript will pick them up. The source files will continue to use the current format.

No, this is not something we're going to do. The `dist/` files do provide JSDoc commens so that TypeScript will pick them up. The source files will continue to use the current format.
onx2 commented 2024-08-16 17:51:40 +02:00 (Migrated from github.com)
Copy link

No, this is not something we're going to do. The dist/ files do provide JSDoc commens so that TypeScript will pick them up. The source files will continue to use the current format.

Fair enough - how about documenting which methods will throw an error? If a library is going to cause a hard application crash I think that sort of thing should be apparent without having to dig into source code.

> No, this is not something we're going to do. The `dist/` files do provide JSDoc commens so that TypeScript will pick them up. The source files will continue to use the current format. Fair enough - how about documenting which methods will throw an error? If a library is going to cause a hard application crash I think that sort of thing should be apparent without having to dig into source code.
marijnh commented 2024-08-16 18:54:51 +02:00 (Migrated from github.com)
Copy link

That's done in prose, in the doc comments.

That's done in prose, in the doc comments.
onx2 commented 2024-08-16 19:31:58 +02:00 (Migrated from github.com)
Copy link

What do you mean by "That's done in prose" - I'm not super familiar with this project / just started testing it out. Do you mind pointing me in the direction of where I can see this info?

When I hover over for intellisense to see the comments I get this:
image

In the reference docs:
image

If you'd like, I'd gladly open a PR to update the docs with this info (unless it already exists somewhere)

What do you mean by "That's done in prose" - I'm not super familiar with this project / just started testing it out. Do you mind pointing me in the direction of where I can see this info? When I hover over for intellisense to see the comments I get this: <img width="1024" alt="image" src="https://github.com/user-attachments/assets/80eea4bc-e40a-46f2-8a24-b1aa64669a7f"> In the [reference docs](https://prosemirror.net/docs/ref/#state.EditorState.toJSON): <img width="1013" alt="image" src="https://github.com/user-attachments/assets/7b6e1b5c-e450-4578-a817-55bd29ea1723"> If you'd like, I'd gladly open a PR to update the docs with this info (unless it already exists somewhere)
marijnh commented 2024-08-16 21:22:50 +02:00 (Migrated from github.com)
Copy link

What do you mean by "That's done in prose"

I mean the exception is mentioned in the doc text (for example here).

> What do you mean by "That's done in prose" I mean the exception is mentioned in the doc text (for example [here](https://prosemirror.net/docs/ref/#transform.Transform.step)).

Pull request closed

This pull request cannot be reopened because the branch was deleted.
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
prosemirror/prosemirror-state!24
No description provided.