docs: comments on reactivity functions (fixes #4832) #4836

defaude · 2021-10-22T11:06:43Z

Not done yet. This is merely a starter so that others can check if I'm going in the right direction.

defaude · 2021-10-22T11:13:28Z

I found that there's no documentation for proxyRefs - neither inline nor on the docs page. This function is (only) used in vue-core's component.ts. Is this intented to be "private" / "internal use only" in component.ts? Then maybe we could move it there, as well? If, however, it's supposed to be a common utility, there should be some doc, right?

defaude · 2021-10-22T11:22:49Z

Also: Maybe we could think about having all API-describing documentation in the actual source code and vue-docs somehow pulls those chapters from there? That way, we wouldn't need to maintain the same doc twice.

defaude · 2021-10-22T11:23:03Z

Allow me to summon @yyx990803 to ask for his opinion on this :)

posva · 2021-10-22T12:31:53Z

This is a nice start but comments should follow https://tsdoc.org/ and use @example, @param and other directives.

I also think adding full examples for all the methods is too much and won't be as practical when hovering definitions. It would be better to keep a short explanation about the functions with links to the actual docs. And maybe add some short code samples, especially for reactivity functions that are not used that often.

defaude · 2021-10-22T12:48:44Z

If we start adding @param tags - what about internal stuff like e.g. computed's debugOptions param?

And: you're leaning towards having a dedicated, exhaustive documentation in vue-docs and a shorter, more brief version in the in-line docs, right?

defaude · 2021-10-22T21:53:45Z

I've shortened the doc blocks a bit and sprinkled some tsdoc goodness, as well. Did not add @returns, though, as this basically just repeats the first sentence (in a way).

For the dev-only params like debugOptions: I've added an empty @param tag and this looks nice in intelliJ (doesn't show up at all).

But in VSCode, this doesn't work: It shows up in the quick doc overlay... Since most devs here are most likely using VSCode, I removed the empty @param tags now (even though intelliJ will highlight this as a missing param doc declaration for me 😅)

defaude · 2021-11-07T17:03:37Z

@posva I hope I've covered all functions that are exported from the reactivity module. What do you think?

Regarding the documentation for proxyRefs in ref.ts, I'm not 100% sure: #4836 (comment)

yyx990803 · 2021-11-26T03:17:19Z

Thanks for the great effort! It will probably take me some time to go over all of them but looking good so far.

netlify · 2022-02-15T19:51:47Z

✅ Deploy Preview for vuejs-coverage ready!

Name	Link
🔨 Latest commit	73e035c161e85dba0a3a67e5044e86e06575febd
🔍 Latest deploy log	https://app.netlify.com/sites/vuejs-coverage/deploys/6262504b565b640008863c67
😎 Deploy Preview	https://deploy-preview-4836--vuejs-coverage.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

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

netlify · 2022-02-15T19:51:47Z

✅ Deploy Preview for vue-next-template-explorer ready!

Name	Link
🔨 Latest commit	73e035c161e85dba0a3a67e5044e86e06575febd
🔍 Latest deploy log	https://app.netlify.com/sites/vue-next-template-explorer/deploys/6262504b19c4ee0008b45f00
😎 Deploy Preview	https://deploy-preview-4836--vue-next-template-explorer.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

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

netlify · 2022-02-15T19:51:48Z

👷 Deploy Preview for vue-sfc-playground processing.

Name	Link
🔨 Latest commit	73e035c161e85dba0a3a67e5044e86e06575febd
🔍 Latest deploy log	https://app.netlify.com/sites/vue-sfc-playground/deploys/6262504b66934c0008c4a63c

defaude · 2022-02-15T19:56:50Z

I was quite occupied with my normal job so I missed that this PR was out of sync. It's updated now so it could be merged again 😇

Fixes #4832

defaude · 2022-04-22T06:53:20Z

Trying to keep this up to date with the main branch here :)

EastSun5566 · 2022-12-25T17:48:16Z

I truly believe that those comments can greatly improve DX! I hope that the Vue team can merge them soon 🙏

defaude · 2023-01-25T22:48:55Z

A belated merry christmas and happy new year to everyone 😘 I've updated the PR so it can be merged again.

posva

Thank you for this! I think it's worth getting multiple pairs of eyes on this PR. I think it will be very welcomed! 😄

packages/reactivity/src/computed.ts

packages/reactivity/src/effect.ts

packages/reactivity/src/effectScope.ts

packages/reactivity/src/ref.ts

packages/reactivity/src/effect.ts

posva

It's looking great but we should definitely address the unresolved reviews as well!
I think that in general, using the vuejs.org API versions (sometimes without the example or with a shorter one) would make up for an overrall more correct, concise, and complete version.

I added a few comments to the remaining comments but I noticed there were more than I expected so I stopped midway 😅

posva · 2023-02-11T13:05:56Z

packages/reactivity/src/effectScope.ts

+ * Provides access to the current effect scope.
+ *
+ * This may be undefined at times when there's no effect active effect scope at
+ * this very moment.


I think we should just align with the API docs on this one: https://vuejs.org/api/reactivity-advanced.html#getcurrentscope (much shorter and complete)

posva · 2023-02-11T13:06:33Z

packages/reactivity/src/reactive.ts

@@ -65,26 +65,33 @@ function getTargetType(value: Target) {
 export type UnwrapNestedRefs<T> = T extends Ref ? T : UnwrapRefSimple<T>

 /**
- * Creates a reactive copy of the original object.
+ * Creates a deeply-reactive copy of the original object.


This still remains

posva · 2023-02-11T13:06:48Z

packages/reactivity/src/reactive.ts

- * Return a shallowly-reactive copy of the original object, where only the root
- * level properties are reactive. It also does not auto-unwrap refs (even at the
- * root level).
+ * Creates a shallowly-reactive copy of the original object.


still remains

posva · 2023-02-11T13:06:56Z

packages/reactivity/src/reactive.ts

@@ -147,8 +164,32 @@ export type DeepReadonly<T> = T extends Builtin
  : Readonly<T>

 /**
- * Creates a readonly copy of the original object. Note the returned copy is not
- * made reactive, but `readonly` can be called on an already reactive object.
+ * Creates a readonly copy of the original object.


still remains

Relates to #4832 I basically copied over most of the documentation text and examples from the docs pages (and potentially merged it with already-existing inline docs).

Co-authored-by: Eduardo San Martin Morote <[email protected]>

Also shorten doc blocks a bit, remove overly-long examples etc.

defaude · 2023-02-18T14:27:54Z

Hey @posva I've shortened the doc blocks a bit, added links to the appropriate docs page where appropriate. What do you think?

posva

Thanks! Almost finished 🙌

posva · 2023-02-20T17:09:05Z

packages/reactivity/src/reactive.ts

@@ -65,26 +65,33 @@ function getTargetType(value: Target) {
 export type UnwrapNestedRefs<T> = T extends Ref ? T : UnwrapRefSimple<T>

 /**
- * Creates a reactive copy of the original object.
+ * Creates a deeply-reactive copy of the original object.


This one hasn't change: it's not a copy

packages/reactivity/src/computed.ts

…gs/param/

posva

Thanks a lot!

defaude · 2023-03-09T09:38:41Z

Hey @posva 👋 Anything else I should do or could/should this be merged now? 🦄

yyx990803 · 2023-03-31T09:05:56Z

@defaude Thanks for your hard work and patience! This is great.

close vuejs#4832

posva changed the title ~~Add documentation for reactivity functions~~ docs: comments on reactivity functions Oct 22, 2021

defaude marked this pull request as ready for review November 7, 2021 16:56

defaude changed the title ~~docs: comments on reactivity functions~~ docs: comments on reactivity functions (fixes #4832) Feb 15, 2022

posva reviewed Jan 27, 2023

View reviewed changes

lmiller1990 reviewed Jan 28, 2023

View reviewed changes

packages/reactivity/src/effect.ts Outdated Show resolved Hide resolved

posva reviewed Feb 11, 2023

View reviewed changes

defaude and others added 9 commits February 18, 2023 09:53

Add inline doc for computed, reactive and ref functions

8a4c961

Relates to #4832 I basically copied over most of the documentation text and examples from the docs pages (and potentially merged it with already-existing inline docs).

Shorten inline docs a bit

8e51437

Drop empty @param tags as they don't behave in VSCode

d7933ce

Add a few more function docs

80c87e8

Update / add a few docs in effect.ts

2421d18

Update / add a few docs in effectScope.ts

8ea1d42

Add doc for proxyRefs

014bf68

Update packages/reactivity/src/effect.ts

7421698

Co-authored-by: Eduardo San Martin Morote <[email protected]>

Update packages/reactivity/src/effectScope.ts

8c80de9

Co-authored-by: Eduardo San Martin Morote <[email protected]>

defaude and others added 7 commits February 18, 2023 09:53

Update packages/reactivity/src/ref.ts

d07d25b

Co-authored-by: Eduardo San Martin Morote <[email protected]>

chore: Add description for computed debugOptions

5706783

chore: doc format

4c7fbe2

chore: reuse docs from docs website

40eaaef

chore: remove doc dupes on overloaded functions

234a7f1

Apply suggestions from code review

b90f4e0

Co-authored-by: Eduardo San Martin Morote <[email protected]>

chore: Update doc blocks with links to docs page

e6f6cf8

Also shorten doc blocks a bit, remove overly-long examples etc.

posva requested changes Feb 20, 2023

View reviewed changes

defaude added 2 commits February 21, 2023 08:21

chore: Align doc blocks of reactive() and computed() with online docs

03b3e96

chore: Fix @param tag syntax to align with https://tsdoc.org/pages/ta…

987c30c

…gs/param/

posva approved these changes Feb 22, 2023

View reviewed changes

yyx990803 merged commit c346af2 into vuejs:main Mar 31, 2023

defaude deleted the feat/4832-add-docs-for-reactivity-functions branch March 31, 2023 14:11

IAmSSH pushed a commit to IAmSSH/core that referenced this pull request May 14, 2023

docs: comments on reactivity functions (fixes vuejs#4832) (vuejs#4836)

b9dee5d

close vuejs#4832

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: comments on reactivity functions (fixes #4832) #4836

docs: comments on reactivity functions (fixes #4832) #4836

defaude commented Oct 22, 2021 •

edited by posva

Loading

defaude commented Oct 22, 2021

defaude commented Oct 22, 2021

defaude commented Oct 22, 2021

posva commented Oct 22, 2021

defaude commented Oct 22, 2021

defaude commented Oct 22, 2021

defaude commented Nov 7, 2021 •

edited

Loading

yyx990803 commented Nov 26, 2021

netlify bot commented Feb 15, 2022 •

edited

Loading

netlify bot commented Feb 15, 2022 •

edited

Loading

netlify bot commented Feb 15, 2022 •

edited

Loading

defaude commented Feb 15, 2022

defaude commented Apr 22, 2022

EastSun5566 commented Dec 25, 2022

defaude commented Jan 25, 2023

posva left a comment

posva left a comment •

edited

Loading

posva Feb 11, 2023

posva Feb 11, 2023

posva Feb 11, 2023

posva Feb 11, 2023

defaude commented Feb 18, 2023

posva left a comment

posva Feb 20, 2023

posva left a comment

defaude commented Mar 9, 2023

yyx990803 commented Mar 31, 2023

docs: comments on reactivity functions (fixes #4832) #4836

docs: comments on reactivity functions (fixes #4832) #4836

Conversation

defaude commented Oct 22, 2021 • edited by posva Loading

defaude commented Oct 22, 2021

defaude commented Oct 22, 2021

defaude commented Oct 22, 2021

posva commented Oct 22, 2021

defaude commented Oct 22, 2021

defaude commented Oct 22, 2021

defaude commented Nov 7, 2021 • edited Loading

yyx990803 commented Nov 26, 2021

netlify bot commented Feb 15, 2022 • edited Loading

✅ Deploy Preview for vuejs-coverage ready!

netlify bot commented Feb 15, 2022 • edited Loading

✅ Deploy Preview for vue-next-template-explorer ready!

netlify bot commented Feb 15, 2022 • edited Loading

👷 Deploy Preview for vue-sfc-playground processing.

defaude commented Feb 15, 2022

defaude commented Apr 22, 2022

EastSun5566 commented Dec 25, 2022

defaude commented Jan 25, 2023

posva left a comment

Choose a reason for hiding this comment

posva left a comment • edited Loading

Choose a reason for hiding this comment

posva Feb 11, 2023

Choose a reason for hiding this comment

posva Feb 11, 2023

Choose a reason for hiding this comment

posva Feb 11, 2023

Choose a reason for hiding this comment

posva Feb 11, 2023

Choose a reason for hiding this comment

defaude commented Feb 18, 2023

posva left a comment

Choose a reason for hiding this comment

posva Feb 20, 2023

Choose a reason for hiding this comment

posva left a comment

Choose a reason for hiding this comment

defaude commented Mar 9, 2023

yyx990803 commented Mar 31, 2023

defaude commented Oct 22, 2021 •

edited by posva

Loading

defaude commented Nov 7, 2021 •

edited

Loading

netlify bot commented Feb 15, 2022 •

edited

Loading

netlify bot commented Feb 15, 2022 •

edited

Loading

netlify bot commented Feb 15, 2022 •

edited

Loading

posva left a comment •

edited

Loading