Fix argument notation in docs

src/array.cr

@@ -804,7 +804,7 @@ class Array(T)
     fill(range) { value }
   end
 
-  # Returns the first `n` elements of the array.
+  # Returns the first *n* elements of the array.
   #
   # ```
   # [1, 2, 3].first(2) # => [1, 2]
@@ -847,7 +847,7 @@ class Array(T)
     to_s io
   end
 
-  # Returns the last `n` elements of the array.
+  # Returns the last *n* elements of the array.
   #
   # ```
   # [1, 2, 3].last(2) # => [2, 3]

src/base64.cr

@@ -26,7 +26,7 @@ module Base64
   private NL = '\n'.ord.to_u8
   private NR = '\r'.ord.to_u8
 
-  # Returns the Base64-encoded version of `data`.
+  # Returns the Base64-encoded version of *data*.
   # This method complies with RFC 2045.
   # Line feeds are added to every 60 encoded characters.
   #
@@ -48,7 +48,7 @@ module Base64
     end
   end
 
-  # Write the Base64-encoded version of `data` to `io`.
+  # Write the Base64-encoded version of *data* to *io*.
   # This method complies with RFC 2045.
   # Line feeds are added to every 60 encoded characters.
   #
@@ -79,7 +79,7 @@ module Base64
     end
   end
 
-  # Returns the Base64-encoded version of `data` with no newlines.
+  # Returns the Base64-encoded version of *data* with no newlines.
   # This method complies with RFC 4648.
   #
   #     require "base64"
@@ -104,7 +104,7 @@ module Base64
     end
   end
 
-  # Write the Base64-encoded version of `data` with no newlines to `io`.
+  # Write the Base64-encoded version of *data* with no newlines to *io*.
   # This method complies with RFC 4648.
   #
   #     require "base64"
@@ -123,13 +123,13 @@ module Base64
     count
   end
 
-  # Returns the Base64-encoded version of `data` using a urlsafe alphabet.
+  # Returns the Base64-encoded version of *data* using a urlsafe alphabet.
   # This method complies with "Base 64 Encoding with URL and Filename Safe
   # Alphabet" in RFC 4648.
   #
   # The alphabet uses '-' instead of '+' and '_' instead of '/'.
   #
-  # The `padding` parameter defaults to true. When false, enough `=` characters
+  # The *padding* parameter defaults to true. When false, enough `=` characters
   # are not added to make the output divisible by 4.
   def urlsafe_encode(data, padding = true) : String
     slice = data.to_slice
@@ -141,7 +141,7 @@ module Base64
     end
   end
 
-  # Write the Base64-encoded version of `data` using a urlsafe alphabet to `io`.
+  # Write the Base64-encoded version of *data* using a urlsafe alphabet to *io*.
   # This method complies with "Base 64 Encoding with URL and Filename Safe
   # Alphabet" in RFC 4648.
   #
@@ -150,7 +150,7 @@ module Base64
     strict_encode_to_io_internal(data, io, CHARS_SAFE, pad: true)
   end
 
-  # Returns the Base64-decoded version of `data` as a `Bytes`.
+  # Returns the Base64-decoded version of *data* as a `Bytes`.
   # This will decode either the normal or urlsafe alphabets.
   def decode(data) : Bytes
     slice = data.to_slice
@@ -160,7 +160,7 @@ module Base64
     Slice.new(buf, appender.size.to_i32)
   end
 
-  # Write the Base64-decoded version of `data` to `io`.
+  # Write the Base64-decoded version of *data* to *io*.
   # This will decode either the normal or urlsafe alphabets.
   def decode(data, io : IO)
     count = 0
@@ -172,7 +172,7 @@ module Base64
     count
   end
 
-  # Returns the Base64-decoded version of `data` as a string.
+  # Returns the Base64-decoded version of *data* as a string.
   # If the data doesn't decode to a valid UTF8 string,
   # *InvalidByteSequenceError* will be raised.
   # This will decode either the normal or urlsafe alphabets.

src/benchmark.cr

@@ -94,9 +94,9 @@ module Benchmark
   # Instruction per second interface of the `Benchmark` module. Yields a `Job`
   # to which one can report the benchmarks. See the module's description.
   #
-  # The optional parameters `calculation` and `warmup` set the duration of
+  # The optional parameters *calculation* and *warmup* set the duration of
   # those stages in seconds. For more detail on these stages see
-  # `Benchmark::IPS`. When the `interactive` parameter is true, results are
+  # `Benchmark::IPS`. When the *interactive* parameter is true, results are
   # displayed and updated as they are calculated, otherwise all at once.
   def ips(calculation = 5, warmup = 2, interactive = STDOUT.tty?)
     {% if !flag?(:release) %}

src/big/big_int.cr

@@ -58,7 +58,7 @@ struct BigInt < Int
     LibGMP.init_set_d(out @mpz, num)
   end
 
-  # Returns `num`. Useful for generic code that does `T.new(...)` with `T`
+  # Returns *num*. Useful for generic code that does `T.new(...)` with `T`
   # being a `Number`.
   def self.new(num : BigInt)
     num

src/big/big_rational.cr

@@ -18,7 +18,7 @@ struct BigRational < Number
 
   # Create a new BigRational.
   #
-  # If `denominator` is 0, this will raise an exception.
+  # If *denominator* is 0, this will raise an exception.
   def initialize(numerator : Int, denominator : Int)
     check_division_by_zero denominator
 
@@ -100,14 +100,14 @@ struct BigRational < Number
     self / other.to_big_r
   end
 
-  # Divides the rational by (2**`other`)
+  # Divides the rational by (2 ** *other*)
   #
   #     BigRational.new(2,3) >> 2 # => 1/6
   def >>(other : Int)
     BigRational.new { |mpq| LibGMP.mpq_div_2exp(mpq, self, other) }
   end
 
-  # Multiplies the rational by (2**`other`)
+  # Multiplies the rational by (2 ** *other*)
   #
   #     BigRational.new(2,3) << 2 # => 8/3
   def <<(other : Int)

src/bit_array.cr

@@ -20,9 +20,9 @@ struct BitArray
   # The number of bits the BitArray stores
   getter size : Int32
 
-  # Create a new BitArray of `size` bits.
+  # Create a new BitArray of *size* bits.
   #
-  # `initial` optionally sets the starting value, true or false, for all bits
+  # *initial* optionally sets the starting value, true or false, for all bits
   # in the array.
   def initialize(@size, initial : Bool = false)
     value = initial ? UInt32::MAX : UInt32::MIN

src/class.cr

@@ -24,7 +24,7 @@ class Class
     {{ @type.name.stringify }}
   end
 
-  # Casts `other` to this class.
+  # Casts *other* to this class.
   #
   # This is the same as using `as`, but allows the class to be passed around as
   # an argument. See the
@@ -40,7 +40,7 @@ class Class
     other.as(self)
   end
 
-  # Returns the union type of `self` and `other`.
+  # Returns the union type of `self` and *other*.
   #
   # ```
   # Int32 | Char # => (Int32 | Char)

src/comparable.cr

@@ -17,7 +17,7 @@ module Comparable(T)
   end
 
   # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns `0`.
-  # Also returns `true` if this and `other` are the same object.
+  # Also returns `true` if this and *other* are the same object.
   def ==(other : T)
     if self.is_a?(Reference)
       # Need to do two different comparisons because the compiler doesn't yet

src/concurrent.cr

@@ -90,7 +90,7 @@ end
 #
 # This is because in the first case all spawned fibers refer to
 # the same local variable, while in the second example copies of
-# `i` are passed to a Proc that eventually invokes the call.
+# *i* are passed to a Proc that eventually invokes the call.
 macro spawn(call, *, name = nil)
   {% if call.is_a?(Call) %}
     ->(

src/deque.cr

@@ -200,7 +200,7 @@ class Deque(T)
     found
   end
 
-  # Delete the item that is present at the `index`. Items to the right of this one will have their indices decremented.
+  # Delete the item that is present at the *index*. Items to the right of this one will have their indices decremented.
   # Raises `IndexError` if trying to delete an element outside the deque's range.
   #
   # ```
@@ -272,7 +272,7 @@ class Deque(T)
     end
   end
 
-  # Insert a new item before the item at `index`. Items to the right of this one will have their indices incremented.
+  # Insert a new item before the item at *index*. Items to the right of this one will have their indices incremented.
   #
   # ```
   # a = Deque{0, 1, 2}
@@ -381,7 +381,7 @@ class Deque(T)
     pop { nil }
   end
 
-  # Removes the last `n` (at most) items in the deque.
+  # Removes the last *n* (at most) items in the deque.
   def pop(n : Int)
     if n < 0
       raise ArgumentError.new("can't pop negative count")
@@ -406,15 +406,15 @@ class Deque(T)
     self
   end
 
-  # Rotates this deque in place so that the element at `n` becomes first.
+  # Rotates this deque in place so that the element at *n* becomes first.
   #
-  # For positive `n`, equivalent to `n.times { push(shift) }`.
-  # For negative `n`, equivalent to `(-n).times { unshift(pop) }`.
+  # For positive *n*, equivalent to `n.times { push(shift) }`.
+  # For negative *n*, equivalent to `(-n).times { unshift(pop) }`.
   def rotate!(n : Int = 1)
     if @size == @capacity
       @start = (@start + n) % @capacity
     else
-      # Turn `n` into an equivalent index in range -size/2 .. size/2
+      # Turn *n* into an equivalent index in range -size/2 .. size/2
       half = @size / 2
       if n.abs >= half
         n = (n + half) % @size - half
@@ -460,7 +460,7 @@ class Deque(T)
     shift { nil }
   end
 
-  # Removes the first `n` (at most) items in the deque.
+  # Removes the first *n* (at most) items in the deque.
   def shift(n : Int)
     if n < 0
       raise ArgumentError.new("can't shift negative count")
@@ -470,7 +470,7 @@ class Deque(T)
     nil
   end
 
-  # Swaps the items at the indices `i` and `j`.
+  # Swaps the items at the indices *i* and *j*.
   def swap(i, j)
     self[i], self[j] = self[j], self[i]
     self

src/env.cr

@@ -14,7 +14,7 @@ require "c/stdlib"
 module ENV
   extend Enumerable({String, String})
 
-  # Retrieves the value for environment variable named `key` as a `String`.
+  # Retrieves the value for environment variable named *key* as a `String`.
   # Raises `KeyError` if the named variable does not exist.
   def self.[](key : String) : String
     fetch(key)
@@ -28,8 +28,8 @@ module ENV
 
   # Sets the value for environment variable named *key* as *value*.
   # Overwrites existing environment variable if already present.
-  # Returns `value` if successful, otherwise raises an exception.
-  # If `value` is nil, the environment variable is deleted.
+  # Returns *value* if successful, otherwise raises an exception.
+  # If *value* is `nil`, the environment variable is deleted.
   def self.[]=(key : String, value : String?)
     if value
       if LibC.setenv(key, value, 1) != 0
@@ -56,13 +56,13 @@ module ENV
   end
 
   # Retrieves a value corresponding to the given *key*. Return the second argument's value
-  # if the key does not exist.
+  # if the *key* does not exist.
   def self.fetch(key, default)
     fetch(key) { default }
   end
 
-  # Retrieves a value corresponding to a key. Return the value of the block if
-  # the key does not exist.
+  # Retrieves a value corresponding to a given *key*. Return the value of the block if
+  # the *key* does not exist.
   def self.fetch(key : String, &block : String -> String? | NoReturn)
     value = LibC.getenv key
     return String.new(value) if value
@@ -95,7 +95,7 @@ module ENV
   end
 
   # Iterates over all `KEY=VALUE` pairs of environment variables, yielding both
-  # the `key` and `value`.
+  # the *key* and *value*.
   #
   #     ENV.each do |key, value|
   #       puts "#{key} => #{value}"

src/http/headers.cr

@@ -71,8 +71,8 @@ struct HTTP::Headers
     values ? concat(values) : nil
   end
 
-  # Returns if among the headers for `key` there is some that contains `word` as a value.
-  # The `word` is expected to match between word boundaries (i.e. non-alphanumeric chars).
+  # Returns if among the headers for *key* there is some that contains *word* as a value.
+  # The *word* is expected to match between word boundaries (i.e. non-alphanumeric chars).
   #
   # ```
   # headers = HTTP::Headers{"Connection" => "keep-alive, Upgrade"}

src/io.cr

@@ -487,7 +487,7 @@ module IO
     end
   end
 
-  # Tries to read exactly `slice.size` bytes from this IO into `slice`.
+  # Tries to read exactly `slice.size` bytes from this IO into *slice*.
   # Raises `EOFError` if there aren't `slice.size` bytes of data.
   #
   # ```
@@ -501,7 +501,7 @@ module IO
     read_fully?(slice) || raise(EOFError.new)
   end
 
-  # Tries to read exactly `slice.size` bytes from this IO into `slice`.
+  # Tries to read exactly `slice.size` bytes from this IO into *slice*.
   # Returns `nil` if there aren't `slice.size` bytes of data, otherwise
   # returns the number of bytes read.
   #
@@ -564,7 +564,7 @@ module IO
     gets '\n', chomp: chomp
   end
 
-  # Reads a line of at most `limit` bytes from this IO.
+  # Reads a line of at most *limit* bytes from this IO.
   # A line is terminated by the `\n` character.
   # Returns `nil` if called at the end of this IO.
   #
@@ -594,7 +594,7 @@ module IO
     gets delimiter, Int32::MAX, chomp: chomp
   end
 
-  # Reads until *delimiter* is found, `limit` bytes are read, or the end of the IO is reached.
+  # Reads until *delimiter* is found, *limit* bytes are read, or the end of the IO is reached.
   # Returns `nil` if called at the end of this IO.
   #
   # ```

src/io/buffered.cr

@@ -248,7 +248,7 @@ module IO::Buffered
     @flush_on_newline
   end
 
-  # Turns on/off IO buffering. When `sync` is set to `true`, no buffering
+  # Turns on/off IO buffering. When *sync* is set to `true`, no buffering
   # will be done (that is, writing to this IO is immediately synced to the
   # underlying IO).
   def sync=(sync)

src/io/hexdump.cr

@@ -12,7 +12,7 @@
 # io = IO::Hexdump.new(socket, output: STDERR, read: true)
 # ```
 #
-# When data is read from `io` it will print something akin to the following on
+# When data is read from *io* it will print something akin to the following on
 # STDERR:
 # ```text
 # 00000000  50 52 49 20 2a 20 48 54  54 50 2f 32 2e 30 0d 0a  PRI * HTTP/2.0..

src/json/mapping.cr

@@ -56,7 +56,7 @@ module JSON
   #
   # This macro also declares instance variables of the types given in the mapping.
   #
-  # If `strict` is true, unknown properties in the JSON
+  # If *strict* is true, unknown properties in the JSON
   # document will raise a parse exception. The default is `false`, so unknown properties
   # are silently ignored.
   macro mapping(properties, strict = false)