Textual improvements (#7656)

* Fix more typos

* Minor BitArray overview docs improvement

* Improve Array.new docs

* Make BigInt documentation visible in the docs

* Fix a typo

* Fix File::Info documentation

* Fix File.size docs

* Improve BigDecimal docs

* Apply @asterite's suggestions

* Extend Info's description

* Remove File#info? from File::Info's docs

* Apply @straight-shoota's suggestion

Co-Authored-By: r00ster91 <r00ster91@protonmail.com>

* It's -> Its

spec/std/file_spec.cr

@@ -1161,7 +1161,7 @@ describe "File" do
   end
 
   describe "touch" do
-    it "creates file if it doesn't exists" do
+    it "creates file if it doesn't exist" do
       with_tempfile("touch-create.txt") do |path|
         File.exists?(path).should be_false
         File.touch(path)

spec/std/file_utils_spec.cr

@@ -97,7 +97,7 @@ describe "FileUtils" do
   end
 
   describe "touch" do
-    it "creates file if it doesn't exists" do
+    it "creates file if it doesn't exist" do
       with_tempfile("touch.txt") do |path|
         File.exists?(path).should be_false
         FileUtils.touch(path)
@@ -137,7 +137,7 @@ describe "FileUtils" do
       end
     end
 
-    it "raises an error if the directory doesn't exists" do
+    it "raises an error if the directory doesn't exist" do
       expect_raises(ArgumentError, "No such directory : not_existing_dir") do
         FileUtils.cp({datapath("test_file.txt")}, "not_existing_dir")
       end

src/array.cr

@@ -59,7 +59,7 @@ class Array(T)
   getter size : Int32
   @capacity : Int32
 
-  # Creates a new empty Array.
+  # Creates a new empty `Array`.
   def initialize
     @size = 0
     @capacity = 0

src/big/big_decimal.cr

@@ -1,20 +1,19 @@
 require "big"
 
-# A `BigDecimal` represents arbitrary precision decimals.
-#
-# It is internally represented by a pair of `BigInt` and `UInt64`: value and scale.
-# Value contains the actual value, and scale tells the decimal point place.
-# e.g. value=1234, scale=2 => 12.34
-#
-# The general idea and some of the arithmetic algorithms were adapted from
-# the MIT/APACHE -licensed https://github.com/akubera/bigdecimal-rs
-
 class InvalidBigDecimalException < Exception
   def initialize(big_decimal_str : String, reason : String)
     super("Invalid BigDecimal: #{big_decimal_str} (#{reason})")
   end
 end
 
+# A `BigDecimal` can represent arbitrarily large precision decimals.
+#
+# It is internally represented by a pair of `BigInt` and `UInt64`: value and scale.
+# Value contains the actual value, and scale tells the decimal point place.
+# E.g. when value is `1234` and scale `2`, the result is `12.34`.
+#
+# The general idea and some of the arithmetic algorithms were adapted from
+# the MIT/APACHE-licensed [bigdecimal-rs](https://github.com/akubera/bigdecimal-rs).
 struct BigDecimal < Number
   ZERO                       = BigInt.new(0)
   TEN                        = BigInt.new(10)

src/bit_array.cr

@@ -1,11 +1,9 @@
-# BitArray is an array data structure that compactly stores bits.
+# `BitArray` is an array data structure that compactly stores bits.
 #
 # Bits externally represented as `Bool`s are stored internally as
 # `UInt32`s. The total number of bits stored is set at creation and is
 # immutable.
 #
-# `BitArray` includes all the methods in `Enumerable`.
-#
 # ### Example
 #
 # ```

src/compiler/crystal/command.cr

@@ -222,7 +222,7 @@ class Crystal::Command
       ensure
         File.delete(output_filename) rescue nil
 
-        # Delete related dwarf generated by dsymutil, if any exists
+        # Delete related dwarf generated by dsymutil, if any exist
         {% if flag?(:darwin) %}
           unless compiler.debug.none?
             File.delete("#{output_filename}.dwarf") rescue nil

src/compiler/crystal/macros.cr

@@ -832,7 +832,7 @@ module Crystal::Macros
 
   # A tuple literal.
   #
-  # It's macro methods are the same as `ArrayLiteral`
+  # Its macro methods are the same as `ArrayLiteral`.
   class TupleLiteral < ASTNode
   end
 

src/compiler/crystal/macros/methods.cr

@@ -2385,12 +2385,12 @@ end
 private def fetch_annotation(node, method, args)
   node.interpret_one_arg_method(method, args) do |arg|
     unless arg.is_a?(Crystal::TypeNode)
-      args[0].raise "argument to '#{node.class_desc}#annotation' must be a TypeNode, not #{arg.class_desc}'"
+      args[0].raise "argument to '#{node.class_desc}#annotation' must be a TypeNode, not #{arg.class_desc}"
     end
 
     type = arg.type
     unless type.is_a?(Crystal::AnnotationType)
-      args[0].raise "argument to '#{node.class_desc}#annotation' must be an annotation type , not #{type} (#{type.type_desc})'"
+      args[0].raise "argument to '#{node.class_desc}#annotation' must be an annotation type, not #{type} (#{type.type_desc})"
     end
 
     value = yield type

src/compiler/crystal/semantic/hooks.cr

@@ -77,7 +77,7 @@ module Crystal
     #
     # ```
     # module Moo
-    #   macro extended
+    #   macro included
     #     puts 1
     #   end
     # end

src/compiler/crystal/syntax/ast.cr

@@ -2075,7 +2075,7 @@ module Crystal
 
   # for inside a macro:
   #
-  #    {% for x1, x2, ... , xn in exp %}
+  #    {% for x1, x2, ..., xn in exp %}
   #      body
   #    {% end %}
   class MacroFor < ASTNode

src/file.cr

@@ -82,23 +82,25 @@ class File < IO::FileDescriptor
   # Opens the file named by *filename*.
   #
   # *mode* must be one of the following file open modes:
+  #
   # ```text
   # Mode | Description
   # -----+------------------------------------------------------
   # r    | Read-only, starts at the beginning of the file.
   # r+   | Read-write, starts at the beginning of the file.
   # w    | Write-only, truncates existing file to zero length or
-  #      | creates a new file if the file doesn't exists.
+  #      | creates a new file if the file doesn't exist.
   # w+   | Read-write, truncates existing file to zero length or
-  #      | creates a new file if the file doesn't exists.
+  #      | creates a new file if the file doesn't exist.
   # a    | Write-only, starts at the end of the file,
-  #      | creates a new file if the file doesn't exists.
+  #      | creates a new file if the file doesn't exist.
   # a+   | Read-write, starts at the end of the file,
-  #      | creates a new file if the file doesn't exists.
-  # rb   | Same as the 'r' mode but in binary file mode.
-  # wb   | Same as the 'w' mode but in binary file mode.
-  # ab   | Same as the 'a' mode but in binary file mode.
+  #      | creates a new file if the file doesn't exist.
+  # rb   | Same as 'r' but in binary file mode.
+  # wb   | Same as 'w' but in binary file mode.
+  # ab   | Same as 'a' but in binary file mode.
   # ```
+  #
   # In binary file mode, line endings are not converted to CRLF on Windows.
   def self.new(filename : Path | String, mode = "r", perm = DEFAULT_CREATE_PERMISSIONS, encoding = nil, invalid = nil)
     filename = filename.to_s
@@ -162,8 +164,8 @@ class File < IO::FileDescriptor
     info(path1, follow_symlinks).same_file? info(path2, follow_symlinks)
   end
 
-  # Returns the size of *filename* bytes. Raises `Errno` if the file at *path*
-  # does not exist.
+  # Returns the size of the file at *filename* in bytes.
+  # Raises `Errno` if the file at *filename* does not exist.
   #
   # ```
   # File.size("foo") # raises Errno

src/file/info.cr

@@ -75,8 +75,8 @@ class File
     end
   end
 
-  # A `File::Info` contains metadata regarding a file. It is returned by
-  # `File.info`, and `File#info`.
+  # A `File::Info` contains metadata regarding a file.
+  # It is returned by `File.info`, `File#info` and `File.info?`.
   abstract struct Info
     # Size of the file, in bytes.
     abstract def size : UInt64

src/int.cr

@@ -169,7 +169,7 @@ struct Int
   #
   # This uses truncated division.
   #
-  # See `Int#div` for more details.
+  # See `Int#tdiv` for more details.
   def remainder(other : Int)
     if other == 0
       raise DivisionByZeroError.new

src/io/memory.cr

@@ -12,7 +12,7 @@ class IO::Memory < IO
   @capacity : Int32
 
   # Creates an empty, resizeable and writeable `IO::Memory` with the given
-  # initialize capactiy for the internal buffer.
+  # initial *capacity* for the internal buffer.
   #
   # ```
   # io = IO::Memory.new

src/mime.cr

@@ -67,7 +67,7 @@ require "crystal/system/mime"
 # The data format must follow the format of `mime.types`: Each line declares
 # a MIME type followed by a whitespace-separated list of extensions mapped to
 # this type. Everything following a `#` is considered a comment until the end of
-# line. Empy line are ignored.
+# line. Empty lines are ignored.
 #
 # ```plain
 # text/html html htm
@@ -128,7 +128,7 @@ module MIME
   # This will neither load the internal defaults nor the OS-provided MIME database,
   # only the database at *filename* (using `.load_mime_database`).
   #
-  # Callig this method repeatedly is allowed.
+  # Calling this method repeatedly is allowed.
   def self.init(filename : String) : Nil
     init(load_defaults: false)
 
@@ -143,32 +143,32 @@ module MIME
 
   # Looks up the MIME type associated with *extension*.
   #
-  # A case sensitive search is tried first, if this yields no result, it is
+  # A case-sensitive search is tried first, if this yields no result, it is
   # matched case-insensitive. Returns *default* if *extension* is not registered.
   def self.from_extension(extension : String, default) : String
     from_extension(extension) { default }
   end
 
   # Looks up the MIME type associated with *extension*.
   #
-  # A case sensitive search is tried first, if this yields no result, it is
+  # A case-sensitive search is tried first, if this yields no result, it is
   # matched case-insensitive. Raises `KeyError` if *extension* is not registered.
   def self.from_extension(extension : String) : String
     from_extension(extension) { raise KeyError.new("Missing MIME type for extension #{extension.inspect}") }
   end
 
   # Looks up the MIME type associated with *extension*.
   #
-  # A case sensitive search is tried first, if this yields no result, it is
+  # A case-sensitive search is tried first, if this yields no result, it is
   # matched case-insensitive. Returns `nil` if *extension* is not registered.
   def self.from_extension?(extension : String) : String?
     from_extension(extension) { nil }
   end
 
   # Looks up the MIME type associated with *extension*.
   #
-  # A case sensitive search is tried first, if this yields no result, it is
-  # matched case-insensitive. Runs the fiven block if *extension* is not registered.
+  # A case-sensitive search is tried first, if this yields no result, it is
+  # matched case-insensitive. Runs the given block if *extension* is not registered.
   def self.from_extension(extension : String, &block)
     initialize_types
 
@@ -177,31 +177,31 @@ module MIME
 
   # Looks up the MIME type associated with the extension in *filename*.
   #
-  # A case sensitive search is tried first, if this yields no result, it is
-  # matched case-insensitive. Returns *default* if *extension* is not registered.
+  # A case-sensitive search is tried first, if this yields no result, it is
+  # matched case-insensitive. Returns *default* if extension is not registered.
   def self.from_filename(filename : String, default) : String
     from_extension(File.extname(filename), default)
   end
 
   # Looks up the MIME type associated with the extension in *filename*.
   #
-  # A case sensitive search is tried first, if this yields no result, it is
+  # A case-sensitive search is tried first, if this yields no result, it is
   # matched case-insensitive. Raises `KeyError` if extension is not registered.
   def self.from_filename(filename : String) : String
     from_extension(File.extname(filename))
   end
 
   # Looks up the MIME type associated with the extension in *filename*.
   #
-  # A case sensitive search is tried first, if this yields no result, it is
+  # A case-sensitive search is tried first, if this yields no result, it is
   # matched case-insensitive. Returns `nil` if extension is not registered.
   def self.from_filename?(filename : String) : String?
     from_extension?(File.extname(filename))
   end
 
   # Looks up the MIME type associated with the extension in *filename*.
   #
-  # A case sensitive search is tried first, if this yields no result, it is
+  # A case-sensitive search is tried first, if this yields no result, it is
   # matched case-insensitive. Runs the fiven block if extension is not registered.
   def self.from_filename(filename : String, &block)
     from_extension(File.extname(filename)) { |extension| yield extension }
@@ -240,7 +240,7 @@ module MIME
     @@extensions.fetch(type) { Set(String).new }
   end
 
-  # tspecial as defined by RFC 1521 and RFC 2045
+  # tspecial as defined by RFC 1521 and RFC 2045.
   private TSPECIAL_CHARACTERS = {'(', ')', '<', '>', '@', ',', ';', ':', '\\', '"', '/', '[', ']', '?', '='}
 
   private def self.parse_media_type(type : String) : String?
@@ -271,7 +271,7 @@ module MIME
     type.byte_slice(0, reader.pos).strip.downcase
   end
 
-  # Reads MIME type mappings from an IO and registers the extension-to-type
+  # Reads MIME type mappings from *io* and registers the extension-to-type
   # relation (see `.register`).
   #
   # The format follows that of `mime.types`: Each line is list of MIME type and

src/mime/media_type.cr

@@ -137,7 +137,7 @@ module MIME
     # Media types are the values in `Content-Type` and `Content-Disposition` HTTP
     # headers (RFC 2183).
     #
-    # Media type is lowercased and trimmed of white space. Param keys are lowercased.
+    # Media type is lowercased and trimmed of whitespace. Param keys are lowercased.
     #
     # Raises `MIME::Error` on error.
     def self.parse(string : String) : MediaType
@@ -149,7 +149,7 @@ module MIME
     # Media types are the values in `Content-Type` and `Content-Disposition` HTTP
     # headers (RFC 2183).
     #
-    # Media type is lowercased and trimmed of white space. Param keys are lowercased.
+    # Media type is lowercased and trimmed of whitespace. Param keys are lowercased.
     #
     # Returns `nil` on error.
     def self.parse?(string : String) : MediaType?

src/prelude.cr

@@ -4,7 +4,7 @@
 # requirement to place these in load order.
 #
 # When adding new files, use alpha-sort when possible. Make sure
-# to also add them to `docs_main.cr` if their content need to
+# to also add them to `docs_main.cr` if their content needs to
 # appear in the API docs.
 
 private macro no_win(stmt)

src/string_pool.cr

@@ -78,7 +78,7 @@ class StringPool
   # pool.empty? # => true
   # pool.get(slice)
   # pool.empty? # => false
-  #  ```
+  # ```
   def get(slice : Bytes)
     get slice.to_unsafe, slice.size
   end

src/time/format/custom/rfc_2822.cr

@@ -80,7 +80,7 @@ struct Time::Format
       end
     end
 
-    # comment or folding white space
+    # comment or folding whitespace
     def cfws?
       in_comment = false
       seen_whitespace = false

src/yaml/nodes/nodes.cr

@@ -139,7 +139,7 @@ module YAML::Nodes
     # This is set by `YAML::Nodes.parse`, and is `nil` by default.
     property value : Node?
 
-    # Creates an alias with tha given *anchor*.
+    # Creates an alias with the given *anchor*.
     def initialize(@anchor : String)
     end