search

dart-lang / site-www

Source for Dart website
https://dart.dev
Other
959 stars 691 forks source link

Test all code excerpts #1803

Closed kwalrath closed 1 year ago

kwalrath commented 5 years ago

This bug replaces #407, which is the equivalent for the pre-dart.dev version of this site. We'll need to be able to test all samples as null safety is released.

New pages that need tests for code excerpts:

Old pages that should have tests for code excerpts, including DartPad code (which in most cases is contained in a Gist):

Lower priority code in new pages:

Other:

Tested to some extent:

Done:

Intentionally not testing:

chalin commented 5 years ago

Kathy, I've moved into the opening comment the work items that used to appear in separate comments. That will make it a bit easier to track.

jddeep commented 4 years ago

@kwalrath So I noticed the src for the Dart cheatsheet codelab to be here https://github.com/dart-lang/site-www/edit/master/src/codelabs/dart-cheatsheet.md. So if were to add the code-excerpt for the code snippet:

int a; // The initial value of a is null.
a ??= 3;
print(a); // <-- Prints 3.

a ??= 5;
print(a); // <-- Still prints 3.

Is there the code file for this snippet already there to be linked or we need to create first? Also should it be just a gist or we should add as .dart file in this repo itself?

kwalrath commented 4 years ago

You've got the right source file for the cheatsheet codelab, although it'd probably be easiest to edit it locally rather than in GitHub.

I believe that all of those samples are untested, and grepping the repo for ??= 3 brings up nothing. Gists aren't testable, so ideally we'd add .dart files to the repo so that Travis will analyze the code, and perhaps actually test it.

Once that code is in your copy of the repo, then in a separate commit (for the same branch & PR) you could add code-excerpt above each excerpt. If you have the local build working, then you can run tool/refresh-code-excerpts.sh to update the code excerpts — and if there are changes/mistakes, you'll see them in the diffs.

Does that make sense?

jddeep commented 4 years ago

Yes, @kwalrath that makes sense. Am on it.

jddeep commented 4 years ago

@kwalrath Adding all the code snippets as in the cheatsheet.md file, into a single dart file, say, dart_cheatsheet.dart isn't feasible cause, in the .md file there are various objects and classes with the same name as for demonstration. So should I go ahead to make separate code files(as fewer files needed) at /misc/bin/ of the repo? If yes, could I open an issue to add the code files for this dart cheatsheet. Once that issue is resolved and we add the needed code files, I can direct to this issue with a PR for the code-excerpts. Please do let me know your thoughts :) Thanks.

kwalrath commented 4 years ago

I'm fine with splitting this up into two PRs, although what I'm about to say next might change your mind...

To deal with multiple objects/classes having the same name, one possibility is to put them in different files, as you said. Another one is to change the names used in the samples, so they aren't all the same. (We generally don't do this, since the names were the same for a reason.) A technique we often use is to have one file with different names for the objects/classes — and then to modify them to be the same name by using replace in the code-excerpt.

I don't remember exactly where I've done the latter, but if you do the following command in your copy of the repo, you can see lots of examples of using replace in the language tour:

$ fgrep -R code-excerpt src/_guides/language/language-tour.md | grep replace

Many of those uses are for the purpose of highlighting (by surrounding it with [!...!]). For example, replace="/async|await/[!$&!]/g" highlights async and await in an excerpt. But other uses are to change the actual displayed code.

For example, instead of having myObject, you could have myObject1, myObject2, etc. and then use replace to change them all to myObject.

jddeep commented 4 years ago

@kwalrath Thanks for letting me know about this technique :) Will implement when I work on the next files. Actually, I have already made different files for the code snippets used in the cheatsheet and will make a PR with the code files now. So should I direct/refer to this issue (#1803) only in that PR body or I should make a separate issue for adding the code files? Thanks.

kwalrath commented 4 years ago

I'd love to see that PR and how Travis likes it. Did you find any issues with the code while creating those files?

It'd probably be good to have a separate issue for adding the cheatsheet code samples. (Then I can add that issue above by the cheatsheet item.) Either you or I can create that issue.

jddeep commented 4 years ago

Nope i didn't find any such issues while creating the files. @kwalrath Could you then open the issue for the same and let me know. Will make the PR and direct to the issue. Thanks :)

jddeep commented 4 years ago

@kwalrath nvm :) have opened the issue for us.

parlough commented 1 year ago

This issue is quite out of date as a lot of progress has been made. I'm going to close this in favor of more specific issues as we determine excerpts are needed.