Starting to resolve my TODO tags

Author: alvinj

_overviews/scala3-book/ca-context-bounds.md

@@ -13,14 +13,13 @@ next-page: ca-given-imports
 - TODO: define "synthesized" and "synthesized arguments"
 {% endcomment %}
 
-
-In many situations the name of a *context parameter* doesn’t have to be mentioned explicitly, since it’s only used in synthesized arguments for other context parameters.
+In many situations the name of a _context parameter_ doesn’t have to be mentioned explicitly, since it’s only used in synthesized arguments for other context parameters.
 In that case you don’t have to define a parameter name, and can just provide the parameter type.
 
 
 ## Background
 
-For example, this `maximum` method takes a *context parameter* of type `Ord`, only to pass it on as an argument to `max`:
+For example, this `maximum` method takes a _context parameter_ of type `Ord`, only to pass it on as an argument to `max`:
 
 ```scala
 def maximum[T](xs: List[A])(using ord: Ord[A]): A =
@@ -37,7 +36,7 @@ def maximum[T](xs: List[A])(using Ord[A]): A =
 
 ## Context bounds
 
-Given that background, a *context bound* is a shorthand syntax for expressing the pattern of, “a context parameter that depends on a type parameter.”
+Given that background, a _context bound_ is a shorthand syntax for expressing the pattern of, “a context parameter that depends on a type parameter.”
 
 Using a context bound, the `maximum` method can be written like this:
 

_overviews/scala3-book/ca-type-classes.md

@@ -8,7 +8,7 @@ next-page: ca-multiversal-equality
 ---
 
 
-A *type class* is an abstract, parameterized type that lets you add new behavior to any closed data type without using sub-typing.
+A _type class_ is an abstract, parameterized type that lets you add new behavior to any closed data type without using sub-typing.
 This is useful in multiple use-cases, for example:
 
 - Expressing how a type you don’t own---from the standard library or a third-party library---conforms to such behavior
@@ -17,9 +17,6 @@ This is useful in multiple use-cases, for example:
 In Scala 3, type classes are just traits with one or more parameters whose implementations are provided by `given` instances.
 
 
-{% comment %}
-TODO: As background, discuss where the name "type class" comes from.
-{% endcomment %}
 
 ## Example
 

_overviews/scala3-book/collections-classes.md

@@ -9,7 +9,6 @@ next-page: collections-methods
 
 
 {% comment %}
-TODO: add a correct hierarchy image
 TODO: mention Array, ArrayDeque, ListBuffer, Queue, Stack, StringBuilder?
 LATER: note that methods like `+`, `++`, etc., are aliases for other methods
 LATER: add links to the Scaladoc for the major types shown here
@@ -29,19 +28,38 @@ When you need more flexibility, see these pages at the end of this section for m
 
 Looking at Scala collections from a high level, there are three main categories to choose from:
 
-- Sequences
-- Maps
-- Sets
+- **Sequences** are a linear collection of elements and may be _indexed_ (like an array) or _linear_ (like a linked list)
+- **Maps** contain a collection of key/value pairs, like a Java `Map`, Python dictionary, or Ruby `Hash`
+- **Sets** are an unordered sequence of unique elements
 
-A _sequence_ is a linear collection of elements and may be _indexed_ (like an array) or _linear_ (like a linked list).
-A _map_ contains a collection of key/value pairs, like a Java `Map`, Python dictionary, or Ruby `Hash`.
-A _set_ is an unordered sequence of unique elements.
 All of those are basic types, and have subtypes for specific purposes, such as concurrency, caching, and streaming.
+In addition to those three main categories, there are other useful collection types, including ranges, stacks, and queues.
 
-In addition to these three main categories, there are other useful collection types, including ranges, stacks, and queues.
-Ranges are demonstrated later in this section.
 
-The following sections introduce the common types you’ll use on a regular basis.
+### Collections hierarchy
+
+As a brief overview, the next three figures show the hierarchy of classes and traits in the Scala collections.
+
+This first figure shows the collections types in package
+_scala.collection_.
+These are all high-level abstract classes or traits, which
+generally have _immutable_ and _mutable_ implementations.
+
+![General collection hierarchy][collections1]
+
+This figure shows all collections in package _scala.collection.immutable_:
+
+![Immutable collection hierarchy][collections2]
+
+And this figure shows all collections in package _scala.collection.mutable_:
+
+![Mutable collection hierarchy][collections3]
+
+Having seen that detailed view of all of the collections types, the following sections introduce some of the common types you’ll use on a regular basis.
+
+{% comment %}
+NOTE: those images come from this page: https://docs.scala-lang.org/overviews/collections-2.13/overview.html
+{% endcomment %}
 
 
 
@@ -617,3 +635,6 @@ When you need more information about specialized collections, see the following
 
 
 [strict]: {% link _overviews/core/architecture-of-scala-213-collections.md %}
+[collections1]: /resources/images/tour/collections-diagram-213.svg
+[collections2]: /resources/images/tour/collections-immutable-diagram-213.svg
+[collections3]: /resources/images/tour/collections-mutable-diagram-213.svg

_overviews/scala3-book/domain-modeling-oop.md

@@ -171,9 +171,6 @@ Protected members are also visible to subclasses of the class.
 In the following, we illustrate some advanced features of Scala and show how they can be used to structure larger software components.
 The examples are adapted from the paper ["Scalable Component Abstractions"][scalable] by Martin Odersky and Matthias Zenger.
 Don’t worry if you don’t understand all the details of the example; it’s primarily intended to demonstrate how to use several type features to construct larger components.
-{% comment %}
-TODO: I’m not sure what I added in that last sentence is accurate or helpful, but I wanted to add a note about why readers shouldn’t worry about understanding the example.
-{% endcomment %}
 
 Our goal is to define a software component with a _family of types_ that can be refined later in implementations of the component.
 Concretely, the following code defines the component `SubjectObserver` as a trait with two abstract type members, `S` (for subjects) and `O` (for observers):