-
Notifications
You must be signed in to change notification settings - Fork 3k
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
docs(spec): show tests in ESDocs #1378
Conversation
@@ -2,6 +2,7 @@ | |||
var Rx = require('../../dist/cjs/Rx'); | |||
var Observable = Rx.Observable; | |||
|
|||
/** @test {bufferCount} */ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Usually these changes just add the tag, but in other cases...
(If) #1364 is landed, does it means this PR need to be updated as well? |
I don't know... it depends whether git is smart to identify that just the filename extension changed, and can merge the new changes. |
Seems we may know after changes are landed :) let's see how it'll goes, since #1364 is not certain to be accepted at this moment. |
This looks great. |
I'll rebase this tomorrow |
Ok, just FYI, this is taking me some stress to rebase. ESDoc explicitly doesn't support TypeScript, so I need to compile all |
@kwonoj we need to coordinate together the rebase I'm doing. I had to do some big changes:
Can you provide some insight why did you change |
Another thing I may change is -import {hot, cold, expectObservable, expectSubscriptions} from '../helpers/marble-testing';
import {DoneSignature, asDiagram, lowerCaseO} from '../helpers/test-helper';
+declare const hot: any;
+declare const cold: any;
+declare const expectObservable: any;
+declare const expectSubscriptions: any; in +import {assertDeepEqual, hot, cold, expectObservable, expectSubscriptions} from './marble-testing';
+global.cold = cold;
+global.hot = hot;
+global.expectObservable = expectObservable;
+global.expectSubscriptions = expectSubscriptions; in The result is that it makes the test file in ESDoc more readable: Otherwise it looks like this: Which is bad since we want tests (specially marble diagrams) to be additional documentation, it should be readable. With TS2JS compilation, we lose those important whitespaces to align the ASCII marble diagrams though. I might need to try again doing a PR to TypeScript so we could add But that has to be in a different PR, of course. |
: It was ergonomics changes to test cases to import helpers explicitly, intention to move forward test help to be modular without patching global variables any more. (though current still does have some) also provides type inferences to helper method too. Global patch would work, loses some conveniences though. Thinking about further plans, I'd like to have explicit export instead of global patching, but do not have great idea to solve this issue with preserving current way. |
modular so that RxJS users can use the helpers too? And which helpers? I assume mainly I think with the current setup that we have (ESDoc only supporting JS/ES, no TS support), we have to do global patch. If we don't global patch e.g. When it comes to type testing our |
: and also was thought about test-helper to, which setup custom assertions to use hot / cold. I think with the current setup that we have (ESDoc only supporting JS/ES, no TS support), we have to do global patch. : Yes, I don't object that. Above comment was if I could achieve both, I'd like to have explicit export without global patching but for now global patching seems way to go for now. |
Yeah, ESDoc not supporting TS is actually quite annoying. I've been able to get around it most of the time. Perhaps we could have looked into some other library that does straight conversion from TS -> docs, but there's probably even less tools that do that type of stuff. Overall, I'm ok with hacking around ESDoc as we can. It's mostly useful. |
: Off-topic, but makes me curious - have we considered TypeDoc? (http://typedoc.io/) i.e unsupported feature we'd like to have, etcs? |
Maybe we could use it, but it's unclear is it beneficial to move at this point. It doesn't seem to support showing the tests, and unclear does it support additional markdown pages organized in an outline. |
: agreed, question's only for curiousity and not suggesting to migrate into. It could be cobsiderable only if pain of using esdoc is unbearable along with all features we'd like to have is being supported in typedoc. |
5390b71
to
6bc98ef
Compare
Rebased. Also notice that I removed |
Sorry, may need another rebase :( I'll check in this once it's rebased. |
Add ESDoc @test tag on each *-spec.js file in order to make it show in the ESDoc page, and also tweak esdoc.json to show tests.
Rebased ✅ :) |
"test": "npm run test_buildonly && npm run test_nobuild", | ||
"test_karma": "karma start karma.conf.js", | ||
"tests2png": "mkdirp tmp/docs/img && cp -r spec/helpers/tests2png tmp/helpers/tests2png && jasmine JASMINE_CONFIG_PATH=spec/support/tests2png.json", | ||
"tests2png": "npm run test_buildonly && mkdirp tmp/docs/img && mkdirp spec-js/support && cp spec/support/*.json spec-js/support/ && JASMINE_CONFIG_PATH=spec/support/tests2png.json jasmine", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
just note : specifying JASMINE_CONFIG_PATH
prior to command jasmine
makes this script windows-incompatible (was reason I changed its order to let jasmine accept it as command argument)
no blocking issue though, I'll amend this later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
interesting to know, sorry for breaking it
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this script is rarely being used, totally ok and I can amend it later quickly. :)
This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
Add ESDoc @test tag on each *-spec.js file in order to make it show in the ESDoc page, and also
tweak esdoc.json to show tests.
To see this page live, open http://rxjs5-esdoc-tests.surge.sh/test.html