Concept blurbs and about.md's reviews

concepts/anonymous-functions/about.md

@@ -7,25 +7,23 @@ Enum.map([1, 2, 3], fn n -> n + 1 end)
 
 Functions in Elixir are treated as first class citizens:
 
-- Can be assigned to variables.
-- Can be passed around like data as arguments and return values.
-- Can be created dynamically.
+- Named and anonymous functions can be assigned to variables.
+- Named and anonymous functions can be passed around like data as arguments and return values.
+- Anonymous functions can be created dynamically.
 
-Anonymous functions are created with the `fn` keyword and invoked with a dot (`.`):
+Anonymous functions are created with the [`fn`][kernel-fn] keyword and invoked with a dot (`.`):
 
 ```elixir
-function_variable = fn param ->
-  param + 1
-end
+function_variable = fn n -> n + 1 end
 
 function_variable.(1)
 # => 2
 ```
 
-Anonymous functions may be created with the [`&` capture shorthand][kernal-capture];
+Anonymous functions may be created with the [`&` capture shorthand][kernal-capture].
 
-- The initial `&` declares the start of the capture expression
-- `&1`, `&2`, and so on refer to the positional arguments of the anonymous function
+- The initial `&` declares the start of the capture expression.
+- `&1`, `&2`, and so on refer to the positional arguments of the anonymous function.
 
   ```elixir
   # Instead of:
@@ -35,13 +33,13 @@ Anonymous functions may be created with the [`&` capture shorthand][kernal-captu
   & abs(&1) + abs(&2)
   ```
 
-- The & capture operator can also be used to [_capture_ existing named function][capture]:
+- The `&` capture operator can also be used to [_capture_ existing named function][capture]:
 
   ```elixir
   # Instead of:
   fn a, b -> a <= b end
 
-  # We can write using the function and the function's arity:
+  # We can capture the function using its name and arity:
   &<=/2
   ```
 

concepts/basics/about.md

@@ -1,22 +1,22 @@
-- Elixir is dynamically-typed
-  - the type of a variable is only checked at run-time
-- Using the match `=/2` operator, we can bind a value of any type to a variable name:
-  - It is possible to re-bind variables
+- Elixir is dynamically-typed.
+  - The type of a variable is only checked at run-time.
+- Using the match [`=/2`][match] operator, we can bind a value of any type to a variable name:
+  - It is possible to re-bind variables.
   - A variable may have any type of value bound to it.
 
 ## Modules
 
-- Modules are the basis of code organization in Elixir.
+- [Modules][modules] are the basis of code organization in Elixir.
   - A module is visible to all other modules.
   - A module is defined with [`defmodule`][defmodule].
 
 ## Named Functions
 
-- All named functions must be defined in a module.
+- All [named functions][functions] must be defined in a module.
 
   - Named functions are defined with [`def`][def].
-  - A named function may be made private from external modules by using [`defp`][defp] instead.
-  - The value of the last line of a function is _implicitly returned_ after it is evaluated
+  - A named function may be made private by using [`defp`][defp] instead.
+  - The value of the last expression in a function is _implicitly returned_.
   - Short functions may also be written using a one-line syntax.
 
   ```elixir
@@ -33,29 +33,28 @@
 
 - Functions are invoked using the full name of the function with the module name.
   - If invoked from within its own module, the module name may be omitted.
-- The arity of a function is often used when referring to a named function
+- The arity of a function is often used when referring to a named function.
 
   - The arity refers to the number of arguments it accepts.
 
   ```elixir
-  def add(x, y, z), do: x + y + z # add/3, because the arity is 3
+  # add/3, because the arity is 3
+  def add(x, y, z), do: x + y + z
   ```
 
 ## Integers
 
-- Integer values are whole numbers written with one or more digits.
-  - You may use underscores to separate large numbers.
-  - Integers support the [basic mathematical operators][operators].
+Integer values are whole numbers written with one or more digits. You can perform [basic mathematical operations][operators] on them.
 
 ## Strings
 
-- [String][string] literals are a sequence of characters surrounded by double quotes.
+[String][string] literals are sequences of characters surrounded by double quotes.
 
 ```elixir
 string = "this is a string! 1, 2, 3!"
 ```
 
-### Standard library
+## Standard library
 
 - The documentation is available online at [hexdocs.pm/elixir][docs].
 - Most built-in data types have a corresponding module, e.g. `Integer`, `Float`, `String`, `Tuple`, `List`.
@@ -78,7 +77,7 @@ string = "this is a string! 1, 2, 3!"
     def function(), do: true
     ```
 
-  - Module may be documented with `@moduledoc` immediately following the module definition
+  - Modules may be documented with `@moduledoc` immediately following the module definition
 
     ```elixir
     defmodule Example do
@@ -90,7 +89,6 @@ string = "this is a string! 1, 2, 3!"
     end
     ```
 
-[functional-programming]: https://en.wikipedia.org/wiki/Functional_programming
 [match]: https://elixirschool.com/en/lessons/basics/pattern-matching/
 [inline-documentation]: https://elixirschool.com/en/lessons/basics/documentation/#inline-documentation
 [operators]: https://elixir-lang.org/getting-started/basic-types.html#basic-arithmetic

concepts/basics/introduction.md

@@ -21,7 +21,7 @@ end
 
 ### Named functions
 
-_Named Functions_ must be defined in a module. Each function can have zero or more arguments. All arguments are dynamically-typed, and the return type is not explicitly declared, it is the type of the value returned. An _access modifier_ can be specified for functions, making only desired functions available for use external to the module. In a function, the value of the last line is _implicitly returned_ to the calling function.
+_Named Functions_ must be defined in a module. Each function can have zero or more arguments. All arguments are dynamically-typed, and the return type is not explicitly declared, it is the type of the value returned. An _access modifier_ can be specified for functions, making only desired functions available for use external to the module. In a function, the value of the last expression is _implicitly returned_ to the calling function.
 
 Invoking a function is done by specifying its module- and function name and passing arguments for each of the function's arguments. The module name may be omitted if the function is invoked inside of the module.
 

concepts/bit-manipulation/about.md

@@ -1,4 +1,11 @@
-[Bitwise binary functions][bitwise-wiki] can be performed on an integers' binary representation using functions from the [Bitwise module][bitwise-hexdocs].
+[Bitwise binary functions][bitwise-wiki] can be performed on integers using functions from the [Bitwise module][bitwise-hexdocs].
+
+- [`&&&/2`][bitwise-and]: bitwise AND
+- [`<<</2`][bitwise-shift-left]: bitwise SHIFT LEFT
+- [`>>>/2`][bitwise-shift-right]: bitwise SHIFT RIGHT
+- [`^^^/2`][bitwise-xor]: bitwise XOR
+- [`|||/2`][bitwise-or]: bitwise OR
+- [`~~~/1`][bitwise-not]: bitwise NOT
 
 ```elixir
 Bitwise.&&&(0b1110, 0b1001)
@@ -10,3 +17,9 @@ Bitwise.^^^(0b1110, 0b1001)
 
 [bitwise-hexdocs]: https://hexdocs.pm/elixir/Bitwise.html
 [bitwise-wiki]: https://en.wikipedia.org/wiki/Bitwise_operation
+[bitwise-and]: https://hexdocs.pm/elixir/Bitwise.html#&&&/2
+[bitwise-shift-left]: https://hexdocs.pm/elixir/Bitwise.html#<<</2
+[bitwise-shift-right]: https://hexdocs.pm/elixir/Bitwise.html#>>>/2
+[bitwise-xor]: https://hexdocs.pm/elixir/Bitwise.html#^^^/2
+[bitwise-or]: https://hexdocs.pm/elixir/Bitwise.html#|||/2
+[bitwise-not]: https://hexdocs.pm/elixir/Bitwise.html#~~~/2

concepts/bit-manipulation/introduction.md

@@ -14,4 +14,4 @@ Bitwise.<<<(1, 2)
 # => 4
 ```
 
-By default, integers are used for bitwise values.
+All bitwise functions only work on integers.

concepts/bit-manipulation/links.json

@@ -2,5 +2,9 @@
   {
     "url": "https://hexdocs.pm/elixir/Bitwise.html",
     "description": "The Bitwise module"
+  },
+  {
+    "url": "https://en.wikipedia.org/wiki/Bitwise_operation#Bitwise_operators",
+    "description": "Bitwise operators - Wikipedia"
   }
 ]

concepts/booleans/about.md

@@ -1,4 +1,4 @@
-Elixir represents true and false values with the boolean type. There are only two values: _true_ and _false_. These values can be bound to a variable and combined with boolean operators ([`and/2`][strict-and], [`or/2`][strict-or], [`not/1`][strict-not]):
+Elixir represents true and false values with the boolean type. There are only two values: `true` and `false`. These values can be combined with boolean operators ([`and/2`][strict-and], [`or/2`][strict-or], [`not/1`][strict-not]):
 
 ```elixir
 true_variable = true and true
@@ -11,7 +11,7 @@ true_variable = not false
 false_variable = not true
 ```
 
-The operators [`and/2`][strict-and], [`or/2`][strict-or], and [`not/1`][strict-not] are strictly boolean which means they require their arguments to be booleans. There are also equivalent boolean operators which that any type of arguments - [`&&/2`][and], [`||/2`][or], and [`!/1`][not].
+The operators [`and/2`][strict-and], [`or/2`][strict-or], and [`not/1`][strict-not] are strictly boolean which means they require their _first_ argument to be a boolean. There are also equivalent boolean operators that work any type of arguments - [`&&/2`][and], [`||/2`][or], and [`!/1`][not].
 
 Boolean operators use _short-circuit evaluation_, which means that expression on the right-hand side of the operator is only evaluated if needed.
 

concepts/booleans/introduction.md

@@ -1,11 +1,11 @@
-Elixir represents true and false values with the boolean type. There are only two values: _true_ and _false_. These values can be bound to a variable:
+Elixir represents true and false values with the boolean type. There are only two values: `true` and `false`.
 
 ```elixir
 true_variable = true
 false_variable = false
 ```
 
-We can evaluate strict boolean expressions using the `and/2`, `or/2`, and `not/1` operator functions.
+We can evaluate strict boolean expressions using the `and/2`, `or/2`, and `not/1` operators.
 
 ```elixir
 true_variable = true and true

concepts/cond/about.md

@@ -10,7 +10,8 @@ end
 
 At least one clause should evaluate to `true` or a run-time error will be raised.
 
-The `cond` conditional is usually used when there are more than two logical branches and each branch has a condition based on different variables. If all the conditions are based on the same variables, a [`case`][case] conditional is a better fit. If there are only two logical branches, use an `if` conditional instead.
+The `cond` conditional is usually used when there are more than two logical branches and each branch has a condition based on different variables. If all the conditions are based on the same variables, a [`case`][case] conditional is a better fit. If there are only two logical branches, use an [`if`][if] conditional instead.
 
 [cond]: https://elixir-lang.org/getting-started/case-cond-and-if.html#cond
 [case]: https://elixir-lang.org/getting-started/case-cond-and-if.html#case
+[if]: https://elixir-lang.org/getting-started/case-cond-and-if.html#if-and-unless

concepts/floating-point-numbers/about.md

@@ -27,7 +27,7 @@ However, those kind of errors are not specific to Elixir. They happen in all pro
 
 ```elixir
 # 3/4
- Float.ratio(0.75)
+Float.ratio(0.75)
 # => {3, 4}
 
 # 3/5
@@ -61,21 +61,32 @@ Integers and floats can be mixed together in a single arithmetic expression. Usi
 # => 6.0
 ```
 
-Floats can be rounded (`round`), rounded up (`ceil`), or rounded down (`floor`) into floats by using [functions from the `Float`][float-ceil] module, or into integers by using [functions from the `Kernel` module][kernel-ceil]. Another method of changing a float into an integer is cutting off its decimal part with [`trunc`][kernel-trunc].
+Floats can be rounded (`round`), rounded up (`ceil`), or rounded down (`floor`).
+
+To round a float into a float, use functions from the `Float` module ([`Float.round`][float-round], [`Float.ceil`][float-ceil], [`Float.floor`][float-floor]). To get an integer instead, use functions from the `Kernel` module ([`round`][kernel-round], [`ceil`][kernel-ceil], [`floor`][kernel-floor]).
+
+Another method of changing a float into an integer is cutting off its decimal part with [`trunc`][kernel-trunc].
 
 ```elixir
 Float.ceil(5.2)
 # => 6.0
 
 ceil(5.2)
 # => 6
+
+trunc(5.2)
+# => 5
 ```
 
 [0.30000000000000004.com]: https://0.30000000000000004.com/
 [evanw.github.io-float-toy]: https://evanw.github.io/float-toy/
 [arbitrary-precision-arithmetic]: https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic
 [kernel-equal]: https://hexdocs.pm/elixir/Kernel.html#==/2
-[kernel-strictly-equal]: https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic
+[kernel-strictly-equal]: https://hexdocs.pm/elixir/Kernel.html#===/2
+[kernel-round]: https://hexdocs.pm/elixir/Kernel.html#round/1
 [kernel-ceil]: https://hexdocs.pm/elixir/Kernel.html#ceil/1
+[kernel-floor]: https://hexdocs.pm/elixir/Kernel.html#floor/1
 [kernel-trunc]: https://hexdocs.pm/elixir/Kernel.html#trunc/1
+[float-round]: https://hexdocs.pm/elixir/Float.html#round/2
 [float-ceil]: https://hexdocs.pm/elixir/Float.html#ceil/2
+[float-floor]: https://hexdocs.pm/elixir/Float.html#floor/2

concepts/integers/about.md

@@ -50,6 +50,6 @@ Integers and floats can be considered equal ([`==`][kernel-equal]) if they have
 
 [arbitrary-precision-arithmetic]: https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic
 [kernel-equal]: https://hexdocs.pm/elixir/Kernel.html#==/2
-[kernel-strictly-equal]: https://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic
+[kernel-strictly-equal]: https://hexdocs.pm/elixir/Kernel.html#===/2
 [integer]: https://hexdocs.pm/elixir/Integer.html
 [integers-in-other-bases]: https://hexdocs.pm/elixir/master/syntax-reference.html#integers-in-other-bases-and-unicode-code-points

exercises/concept/secrets/.docs/introduction.md

@@ -2,9 +2,9 @@
 
 Functions are treated as first class citizens in Elixir. This means functions:
 
-- Can be assigned to variables.
-- Can be passed around like data as arguments and return values.
-- Can be created dynamically.
+- Named and anonymous functions can be assigned to variables.
+- Named and anonymous functions can be passed around like data as arguments and return values.
+- Anonymous functions can be created dynamically.
 
 Anonymous functions, in contrast to named functions, don't have a static reference available to them, they are only available if they are assigned to a variable or immediately invoked.
 
@@ -64,4 +64,4 @@ Bitwise.<<<(1, 2)
 # => 4
 ```
 
-By default, integers are used for bitwise values.
+All bitwise functions only work on integers.