Updated Operators section in our Collections guide #6525

antfitch · 2025-04-10T22:06:29Z

This PR refactors the Operators section of our Collections guide. This change is to prepare for the addition of the null-aware elements for collections.

Preview:

https://dart-dev--pr6525-dart-null-awareness-elements-ujtoc8s3.web.app/language/collections#supplementals

Overview of changes:

I've changed the name Operators to Supplementals to make it clear that Operators is not a collection type. Also, this section will need to hold more than operators soon.
I have moved each supplemental item into its own section so that they are easier to find in the right TOC.
The examples were difficult for me to follow and the output of the examples was not provided. I added output and updated the examples to be easy for someone to copy and paste into DartPad and test.
I think we needed to clarify what type of null is supported by our spread operators. Not supported (list = null), Supported (list = [1, null, 2]).
I had all of the examples in our excerpt library, but I removed a few that triggered analysis failures due to the following reasons:
- examples that trigger error cases on purpose (ex: show what happens when you pass a null list into another list using the spread operaton.
- a value that is helpful for showing something, but never reached in an excerpt. In the following example, 2 is never reached.
```
var includeItem = true;
var items = [0, if (includeItem) 1, if (!includeItem) 2, 3]; // [0, 1, 3]
```

I’ve reviewed the contributor guide and applied the relevant portions to this PR.
This PR doesn't contain automatically generated corrections or text (Grammarly, LLMs, and similar).
This PR follows the Google Developer Documentation Style Guidelines — for example, it doesn't use i.e. or e.g., and it avoids I and we (first person).
This PR uses semantic line breaks of 80 characters or fewer.

Contribution guidelines:

See our contributor guide for general expectations for PRs.
Larger or significant changes should be discussed in an issue before creating a PR.
Code changes should generally follow the Dart style guide and use dart format.
Updates to code excerpts indicated by <?code-excerpt need to be updated in their source .dart file as well.

dart-github-bot · 2025-04-10T22:09:04Z

Visit the preview URL for this PR (updated for commit 52470f3):

https://dart-dev--pr6525-dart-null-awareness-elements-ujtoc8s3.web.app

munificent

A bunch of feedback here and there but overall I really like the improvement.

examples/misc/lib/language_tour/misc/null_aware_spread_operator_in_collection_a.dart

src/content/language/collections.md

antfitch · 2025-04-15T23:20:15Z

@parlough I've made some large changes after the first review. Here's an overview:

We're now using the term 'element' to describe items in collections.
From the discussion above, it seems like all of these supplementals are actually different types of elements that you can add to a collection. I've updated headings to reflect this.
I've added a comment above each code sample that does not have an excerpt with a reason. This is so we can keep track of samples that don't have them on purpose.
Added the various syntax structures that can be used for each element.
Added a new section called Nesting elements that shows various ways you can nest elements. It also sounds like this is a super power of Dart that isn't available in many other languages, so that's pretty cool.
I've used one code excerpt per code sample. This was to keep things simple. I've also included a print statement in the excerpts (not visible in code samples) so that we can quickly copy & paste to test the code sample and then update the docs with the results.

parlough

Thanks for the extensive work on this @antfitch and for your patience on me reviewing it.

I love these additions, especially the extra examples and showing off more features (else, if-case, nesting, etc).

Overall these additions are a huge improvement. I just have one main concern about the conflation of "element" and some other minor suggestions to consider. Feel free to push back on anything and I'm happy to talk over any of my comments offline as well.

Thanks so much! :D

site-shared

parlough · 2025-04-18T20:10:28Z

src/content/language/collections.md

+Lists use zero-based indexing, where 0 is the index of the first element
+and `list.length - 1` is the index of the last element. 


This change (here and across the page) is what we were purposely trying to avoid in the past as it conflates elements in a collection literal versus actual values in a list.

A single collection element in a collection literal might result in no or even many values in a list, so I think the distinction is still quite important to keep.

I'd be happy to chat through this though.

I do think that element is the more conventional term that developers are used to seeing.

I'm a huge fan of the Python reference documentation and I love how element is used in these two places:

https://docs.python.org/3/library/stdtypes.html#lists

https://docs.python.org/3/library/stdtypes.html#common-sequence-operations

@munificent what are your thoughts? Also, I am using the term element with the set and map collection types. I hesitated with map, but decided that technically, each key-value pair lives inside of an element in a map. If this is a stretch and not factually correct, let me know.

I know it's what developers might be used to seeing, but I'm not sure that familiarity is worth the confusion from one term being used to mean both syntactical elements in a collection literal and actual values in a list.

When reading the page with "element" being used for both, it is quite confusing for me and I'm familiar with the distinction.

See #2631 (comment) for some other background.

Maybe we could have a call about it?

src/content/language/collections.md

examples/misc/lib/language_tour/misc/for_loop_in_collection_a.dart

parlough · 2025-04-18T21:04:43Z

src/content/language/collections.md

+]; // [oneThing, [multiple_a, multiple_b], things]
+```
+
+You can nest all kinds of elements arbitrarily deep.


Is it worth clarifying besides the leaf elements (expressions and map entries)?

Can you tell me more? I'm not sure what to update here exactly.

Co-authored-by: Parker Lougheed <[email protected]>

parlough

Thanks so much for all of those adjustments and this amazing set of docs @antfitch!

The further changes mostly look great to me and I love that the new snippets have some tests as well. I do think we should consider surfacing those expect calls instead of the comments in the future too ;)

Most of my remaining comments are minor, but I still have some concerns about conflating "element". I left some comments adding more details about why, but we could also have a call to chat more. We could also land your current usages and I could open a follow-up PR with the adjustments I was thinking and we could discuss that. Up to you! :)

parlough · 2025-04-22T16:07:44Z

examples/misc/test/language_tour/collections/if_case_operator_in_collection_a.dart

+
+void main() {
+  // #docregion code_sample
+  dynamic data = 123;


We generally try to avoid using dynamic in code examples, so consider changing the type here to Object.

Suggested change

dynamic data = 123;

Object data = 123;

Another option is just using var or final and ignoring the resulting pattern_never_matches_value_type diagnostic for the file.

parlough · 2025-04-22T16:08:32Z

examples/misc/test/language_tour/collections/if_case_operator_in_collection_b.dart

+
+void main() {
+  // #docregion code_sample
+  var orderDetails = ['Apples', 12, ''];


Cool sample!

parlough · 2025-04-22T16:09:09Z

examples/misc/test/language_tour/collections/for_loop_in_collection_a.dart

Thanks for going back and adding tests for all of these snippets! That will be super helpful for us keeping them up to date and accurate.

parlough · 2025-04-22T16:12:02Z

site-shared

Thanks for reupdating this!

As a note, whenever you update your main branch, if git status shows site-shared as having changes, run git submodule update to update your local submodule to match main.

parlough · 2025-04-22T16:12:11Z

src/content/language/collections.md

-a comma separated list of expressions or values,
-enclosed in square brackets (`[]`).
-Here's a simple Dart list:
+Dart list literals are denoted by a comma separated list of


Suggested change

Dart list literals are denoted by a comma separated list of

Dart list literals are denoted by a comma-separated list of

parlough · 2025-04-22T16:22:35Z

src/content/language/collections.md

+  return [
+    executable,
+    ...options,
+    ...extraOptions, // <-- OK now.


Should this comment state that this is an error, not OK?

parlough · 2025-04-22T16:23:52Z

src/content/language/collections.md

+// include the first result, otherwise include the second
+// result.


Consider adjusting the break here to better collocate the "otherwise" clause.

Suggested change

// include the first result, otherwise include the second

// result.

// include the first result, otherwise,

// include the second result.

parlough · 2025-04-22T16:24:02Z

src/content/language/collections.md

+// include the first result, otherwise, perform the second
+// operation.


Consider adjusting the break here to better collocate the "otherwise" clause.

Suggested change

// include the first result, otherwise, perform the second

// operation.

// include the first result, otherwise,

// perform the second operation.

parlough · 2025-04-22T16:24:20Z

src/content/language/collections.md

+
+### If elements {: #if-element }
+
+You can use an `if` element inside of a collection


Suggested change

You can use an `if` element inside of a collection

You can use an `if` element inside of a collection literal

parlough · 2025-04-22T16:32:19Z

src/content/language/collections.md

+In a collection, an element is an individual item in that
+collection. These types of elements are supported in
+a collection:


This is where the confusion of "element" that I mentioned particularly shows up.

The following h3 subsections are talking about elements in a collection literal, but this intro conflates items in actual collections and the elements in a literal. This mostly affects the usage of "individual item" as the collection elements can result in multiple items.

Suggested change

In a collection, an element is an individual item in that

collection. These types of elements are supported in

a collection:

Collection elements are the syntactical constructs

used within collection literals to define the

resulting collection's initial contents.

These types of elements are supported in a collection:

antfitch added 3 commits April 10, 2025 14:23

Refactor the supplementals for collections.

4d9d975

Refactor the supplementals for collections.

78fde9c

add code examples for updated supplementals.

fe5fa9f

antfitch requested review from munificent and parlough April 10, 2025 22:07

antfitch self-assigned this Apr 10, 2025

antfitch added the p.collections label Apr 10, 2025

Update broken links.

e8bf779

munificent approved these changes Apr 11, 2025

View reviewed changes

antfitch marked this pull request as draft April 12, 2025 00:27

antfitch added 2 commits April 15, 2025 16:11

Refine the supplementals section.

ca6abac

Add new code excerpts.

27b1f54

antfitch added 2 commits April 15, 2025 16:22

Heading tweaks.

9d5e1ac

Added one additional example, fixed a link.

f1f8379

parlough reviewed Apr 18, 2025

View reviewed changes

antfitch and others added 11 commits April 18, 2025 16:57

Update src/content/language/collections.md

97fa503

Co-authored-by: Parker Lougheed <[email protected]>

Update src/content/language/collections.md

7bea1d5

Co-authored-by: Parker Lougheed <[email protected]>

Update src/content/language/collections.md

deda895

Co-authored-by: Parker Lougheed <[email protected]>

Update src/content/language/collections.md

e574111

Co-authored-by: Parker Lougheed <[email protected]>

Update src/content/language/collections.md

cf21df5

Co-authored-by: Parker Lougheed <[email protected]>

Update src/content/language/collections.md

a4c30c7

Co-authored-by: Parker Lougheed <[email protected]>

Next round of edits added.

f25090e

Update site-shared

6ba0210

Fixed a merge conflict.

10f1557

Updated an excerpt.

a4bffaf

Merge branch 'main' into dart_null_awareness_elements

52470f3

parlough approved these changes Apr 22, 2025

View reviewed changes

parlough marked this pull request as ready for review April 22, 2025 16:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updated Operators section in our Collections guide #6525

Updated Operators section in our Collections guide #6525

antfitch commented Apr 10, 2025 •

edited

Loading

dart-github-bot commented Apr 10, 2025 •

edited

Loading

munificent left a comment

antfitch commented Apr 15, 2025 •

edited

Loading

parlough left a comment

parlough Apr 18, 2025

antfitch Apr 18, 2025

parlough Apr 22, 2025

parlough Apr 18, 2025

antfitch Apr 21, 2025

parlough left a comment

parlough Apr 22, 2025

parlough Apr 22, 2025

parlough Apr 22, 2025

parlough Apr 22, 2025

parlough Apr 22, 2025

parlough Apr 22, 2025

parlough Apr 22, 2025

parlough Apr 22, 2025

parlough Apr 22, 2025

parlough Apr 22, 2025

		Lists use zero-based indexing, where 0 is the index of the first element
		and `list.length - 1` is the index of the last element.

	Dart list literals are denoted by a comma separated list of
	Dart list literals are denoted by a comma-separated list of

		// include the first result, otherwise include the second
		// result.

		// include the first result, otherwise, perform the second
		// operation.


		### If elements {: #if-element }

		You can use an `if` element inside of a collection

-In a collection, an element is an individual item in that
-collection. These types of elements are supported in
-a collection:
+Collection elements are the syntactical constructs
+used within collection literals to define the
+resulting collection's initial contents.
+These types of elements are supported in a collection:

Updated Operators section in our Collections guide #6525

Are you sure you want to change the base?

Updated Operators section in our Collections guide #6525

Conversation

antfitch commented Apr 10, 2025 • edited Loading

dart-github-bot commented Apr 10, 2025 • edited Loading

munificent left a comment

Choose a reason for hiding this comment

antfitch commented Apr 15, 2025 • edited Loading

parlough left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

parlough left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

antfitch commented Apr 10, 2025 •

edited

Loading

dart-github-bot commented Apr 10, 2025 •

edited

Loading

antfitch commented Apr 15, 2025 •

edited

Loading