From 3e0eb31a65d2ea62fb393475cfeaa46d46f531b2 Mon Sep 17 00:00:00 2001 From: r00ster Date: Sat, 5 Oct 2019 15:59:31 +0200 Subject: [PATCH] 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 * It's -> Its --- spec/std/file_spec.cr | 2 +- spec/std/file_utils_spec.cr | 4 ++-- src/array.cr | 2 +- src/big/big_decimal.cr | 17 ++++++++-------- src/bit_array.cr | 4 +--- src/compiler/crystal/command.cr | 2 +- src/compiler/crystal/macros.cr | 2 +- src/compiler/crystal/macros/methods.cr | 4 ++-- src/compiler/crystal/semantic/hooks.cr | 2 +- src/compiler/crystal/syntax/ast.cr | 2 +- src/file.cr | 20 +++++++++--------- src/file/info.cr | 4 ++-- src/int.cr | 2 +- src/io/memory.cr | 2 +- src/mime.cr | 28 +++++++++++++------------- src/mime/media_type.cr | 4 ++-- src/prelude.cr | 2 +- src/string_pool.cr | 2 +- src/time/format/custom/rfc_2822.cr | 2 +- src/yaml/nodes/nodes.cr | 2 +- 20 files changed, 54 insertions(+), 55 deletions(-) diff --git a/spec/std/file_spec.cr b/spec/std/file_spec.cr index 8002a5cc0081..7f691a401652 100644 --- a/spec/std/file_spec.cr +++ b/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) diff --git a/spec/std/file_utils_spec.cr b/spec/std/file_utils_spec.cr index b950306a86cf..c89f224fc9ac 100644 --- a/spec/std/file_utils_spec.cr +++ b/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 diff --git a/src/array.cr b/src/array.cr index 5c0dce82cfe9..8298d2c42f56 100644 --- a/src/array.cr +++ b/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 diff --git a/src/big/big_decimal.cr b/src/big/big_decimal.cr index b9cd35482a2f..611d5e87c568 100644 --- a/src/big/big_decimal.cr +++ b/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) diff --git a/src/bit_array.cr b/src/bit_array.cr index 0590648b2d4c..4fa3c0d5f74e 100644 --- a/src/bit_array.cr +++ b/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 # # ``` diff --git a/src/compiler/crystal/command.cr b/src/compiler/crystal/command.cr index 333b529d69f2..bfbf3e3d899e 100644 --- a/src/compiler/crystal/command.cr +++ b/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 diff --git a/src/compiler/crystal/macros.cr b/src/compiler/crystal/macros.cr index 3f2766a20054..311683b15e78 100644 --- a/src/compiler/crystal/macros.cr +++ b/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 diff --git a/src/compiler/crystal/macros/methods.cr b/src/compiler/crystal/macros/methods.cr index 6ecdb954daa0..71145c14c552 100644 --- a/src/compiler/crystal/macros/methods.cr +++ b/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 diff --git a/src/compiler/crystal/semantic/hooks.cr b/src/compiler/crystal/semantic/hooks.cr index 4c6aa8feaa36..185bd1e43338 100644 --- a/src/compiler/crystal/semantic/hooks.cr +++ b/src/compiler/crystal/semantic/hooks.cr @@ -77,7 +77,7 @@ module Crystal # # ``` # module Moo - # macro extended + # macro included # puts 1 # end # end diff --git a/src/compiler/crystal/syntax/ast.cr b/src/compiler/crystal/syntax/ast.cr index 7b5b8be6ea42..8796574de0dc 100644 --- a/src/compiler/crystal/syntax/ast.cr +++ b/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 diff --git a/src/file.cr b/src/file.cr index 85804b0c02a5..72b7988ff623 100644 --- a/src/file.cr +++ b/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 diff --git a/src/file/info.cr b/src/file/info.cr index e00dcc4fbee5..07f9a187e6ce 100644 --- a/src/file/info.cr +++ b/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 diff --git a/src/int.cr b/src/int.cr index 1dad0cf71a8a..cb4c1360a953 100644 --- a/src/int.cr +++ b/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 diff --git a/src/io/memory.cr b/src/io/memory.cr index 135955443471..4a2f0d51852d 100644 --- a/src/io/memory.cr +++ b/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 diff --git a/src/mime.cr b/src/mime.cr index 8773d101c54d..4cbf22d04054 100644 --- a/src/mime.cr +++ b/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,7 +143,7 @@ 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 } @@ -151,7 +151,7 @@ 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. 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}") } @@ -159,7 +159,7 @@ 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 `nil` if *extension* is not registered. def self.from_extension?(extension : String) : String? from_extension(extension) { nil } @@ -167,8 +167,8 @@ module MIME # 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,15 +177,15 @@ 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)) @@ -193,7 +193,7 @@ 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 + # 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)) @@ -201,7 +201,7 @@ 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 + # 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 diff --git a/src/mime/media_type.cr b/src/mime/media_type.cr index f2f2cf904106..18fad844ff43 100644 --- a/src/mime/media_type.cr +++ b/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? diff --git a/src/prelude.cr b/src/prelude.cr index 071014d46ff1..c72472ccc59f 100644 --- a/src/prelude.cr +++ b/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) diff --git a/src/string_pool.cr b/src/string_pool.cr index 557c71545f7e..e02a707e59f0 100644 --- a/src/string_pool.cr +++ b/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 diff --git a/src/time/format/custom/rfc_2822.cr b/src/time/format/custom/rfc_2822.cr index 711f10938214..24dc2ca26267 100644 --- a/src/time/format/custom/rfc_2822.cr +++ b/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 diff --git a/src/yaml/nodes/nodes.cr b/src/yaml/nodes/nodes.cr index b57da43c19cf..dc5d151cf677 100644 --- a/src/yaml/nodes/nodes.cr +++ b/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