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

Link to createStubInstance util.md docs in stubs.md #2577

Merged
merged 1 commit into from
Jan 9, 2024

Conversation

DanKaplanSES
Copy link
Contributor

Purpose (TL;DR) - mandatory

The Utilities documentation contains valuable information about createStubInstance, but I didn't see any way to know that unless you happen to have already viewed the Utilities page.

Alternatively, could it make sense to move all of the createStubInstance docs into stubs.md? For me, that's where I would expect to find everything there is to know about createStubInstance, or at least the behavior it provides.

How to verify - mandatory

  1. Check out this branch
  2. npm install

Checklist for author

  • npm run lint passes
  • References to standard library functions are cached.

The Utilities documentation contains valuable information about `createStubInstance`, but I didn't see any way to know that unless you happen to have already viewed the Utilities page. 

Alternatively, could it make sense to move all of the `createStubInstance` docs into stubs.md? For me, that's where I would expect to find everything there is to know about `createStubInstance`, or at least the behavior it provides.
Copy link

codecov bot commented Jan 9, 2024

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (adcf936) 96.02% compared to head (15b2b33) 96.02%.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #2577   +/-   ##
=======================================
  Coverage   96.02%   96.02%           
=======================================
  Files          40       40           
  Lines        1912     1912           
=======================================
  Hits         1836     1836           
  Misses         76       76           
Flag Coverage Δ
unit 96.02% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@fatso83
Copy link
Contributor

fatso83 commented Jan 9, 2024

Alternatively, could it make sense to move all of the createStubInstance docs into stubs.md

I get it from the name, but it's not a method on the stubs object, and it's mostly similar by name only. If it should be moved somewhere, I guess it would be on the sandbox, if anything. But linking from different docs is highly effective and we should only do it more than we do.

I know the docs are far from perfect, but it's what we have now. I know @mroderick is cooking on something, but I don't know the state of it, just that it probably will be different in some way (not sure of the goals ATM, just that it should be better :) ).

@fatso83 fatso83 merged commit cbae699 into sinonjs:main Jan 9, 2024
9 checks passed
@DanKaplanSES
Copy link
Contributor Author

@fatso83

I guess it would be on the sandbox, if anything. But linking from different docs is highly effective and we should only do it more than we do.

Hm, that's interesting. Until your comment on this issue, I didn't realize this was documented in three places. Should I submit a PR to add links to the other docs in these places?

@fatso83
Copy link
Contributor

fatso83 commented Jan 10, 2024

It doesn't mean that the docs are correct, though ... I see that the docs say that there is a difference between the sinon. createStubInstance and sandbox.createStubInstance, but that might be leftovers from the Sinon 1.x days. As of Sinon 2.0, the default sinon instance is a sandbox. Cannot see how they are different (please test if you think otherwise)? So I'd rather just have the docs in one place and just link to that.

@DanKaplanSES
Copy link
Contributor Author

So I'd rather just have the docs in one place and just link to that.

I think I understand but I'm not 100% sure. In other words, the sandbox documentation should be the one and only place to document createStubInstance and the stub/util documents should mostly link to it.

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.

2 participants