Improve documentation wording

Author: preciz

CHANGELOG.md

@@ -1,44 +1,44 @@
 # Changelog for Abit
 
 ## v0.4.0
-  * Feature - Implemented fast atomics resetting via `Abit.clear/1` and `Abit.Counter.clear/1`.
-  * Feature - Implemented bit toggling via `Abit.toggle_bit_at/2` and `Abit.Bitmask.toggle_bit_at/2`.
-  * Feature - Implemented set theory missing operations: `Abit.difference/2`, `Abit.symmetric_difference/2`, and `Abit.invert/1`.
-  * Deprecation - `Abit.merge/2` is deprecated in favor of `Abit.union/2` to align with standard set theory terminology.
+  * Feature - Added fast atomics resetting via `Abit.clear/1` and `Abit.Counter.clear/1`.
+  * Feature - Added bit toggling via `Abit.toggle_bit_at/2` and `Abit.Bitmask.toggle_bit_at/2`.
+  * Feature - Added the missing set operations: `Abit.difference/2`, `Abit.symmetric_difference/2`, and `Abit.invert/1`.
+  * Deprecation - Deprecated `Abit.merge/2` in favor of `Abit.union/2` to align with standard set theory terminology.
 
 ## v0.3.3
-  * Feature - `Abit.Atomics` implements `serialize/1` and `deserialize/1` functions.
+  * Feature - Added `Abit.Atomics.serialize/1` and `Abit.Atomics.deserialize/1`.
 
 ## v0.3.2
-  * Fix - compile warning about using `^^^/2` in `Abit.Counter`
+  * Fix - Fixed a compile warning caused by using `^^^/2` in `Abit.Counter`.
 
 ## v0.3.1
-  * Fix - work with elixir 1.7 by not using Kernel.floor/1 & Kernel.ceil/1
+  * Fix - Restored compatibility with Elixir 1.7 by avoiding `Kernel.floor/1` and `Kernel.ceil/1`.
 
 ## v0.3.0
-  * BREAKING - removed `Abit.Matrix` module. Extracted to [matrax](https://hex.pm/packages/matrax).
+  * BREAKING - Removed `Abit.Matrix` and extracted it to [matrax](https://hex.pm/packages/matrax).
 
 ## v0.2.4
-  * Feature - `Abit.Counter` implements `Enumerable` protocol
+  * Feature - Implemented the `Enumerable` protocol for `Abit.Counter`.
 
 ## v0.2.3
-  * Feature - `Abit.Matrix` implements `add/3`, `exchange/3`, `compare_exchange/4`, `min/1`, `max/1`, ... functions.
-  * Feature - `Abit.Matrix` implements the `Enumerable` protocol
-  * Feature - `Abit.Bitmask` implements `to_list/2` function.
-  * Feature - `Abit` implements `to_list/1` function.
+  * Feature - Added `add/3`, `exchange/3`, `compare_exchange/4`, `min/1`, `max/1`, and other functions to `Abit.Matrix`.
+  * Feature - Implemented the `Enumerable` protocol for `Abit.Matrix`.
+  * Feature - Added `Abit.Bitmask.to_list/2`.
+  * Feature - Added `Abit.to_list/1`.
 
 ## v0.2.2
-  * Feature - `Abit.Matrix` module for working with atomics as an M x N matrix.
+  * Feature - Added `Abit.Matrix` for working with atomics as an M x N matrix.
 
 ## v0.2.1
-  * Performance - improvements for the `Abit` & `Abit.Bitmask` module functions
+  * Performance - Improved the performance of functions in `Abit` and `Abit.Bitmask`.
 
 ## v0.2.0
 
 ### Abit
-  * BREAKING - renamed function `set_bit/3` to `set_bit_at/3` to make it consistent with the API of the Bitmask module.
+  * BREAKING - Renamed `set_bit/3` to `set_bit_at/3` for consistency with the `Abit.Bitmask` API.
 
 ### Abit.Counter
-  * BREAKING - Added an option `wrap_around` to set wrap around behavior. By default wrap around is disabled from now on.
-  * BREAKING - Using built-in signed/unsigned implementation of integer matching instead of the custom one. Signed integers now wrap around the same way as in Elixir.
-  * BREAKING - The return value of `put/3` and `add/3` changed to `{:ok, {index, final_value}}` or `{:error, :value_out_of_bounds}` if the option `wrap_around` is set to false and value is out of bounds.
+  * BREAKING - Added the `wrap_around` option. Wraparound is now disabled by default.
+  * BREAKING - Replaced the custom signed and unsigned integer matching with the built-in implementation. Signed integers now wrap around as they do in Elixir.
+  * BREAKING - Changed the return value of `put/3` and `add/3` to `{:ok, {index, final_value}}`, or `{:error, :value_out_of_bounds}` when `wrap_around` is `false` and the value is out of bounds.

README.md

@@ -8,7 +8,7 @@ Documentation can be found at [https://hexdocs.pm/abit](https://hexdocs.pm/abit)
 
 ## Installation
 
-**Note**: it requires OTP-21.2.1 or later.
+**Note**: Abit requires OTP 21.2.1 or later.
 
 Add `abit` to your list of dependencies in `mix.exs`:
 
@@ -24,42 +24,42 @@ end
 See [https://hexdocs.pm/abit](https://hexdocs.pm/abit) for full documentation.
 
 ### Abit - use `:atomics` as a bit array
-* `Abit.bit_count/1` - Returns count of bits in atomics.
-* `Abit.union/2` - Unions bits of 2 atomics using Bitwise OR.
-* `Abit.intersect/2` - Intersects bits of 2 atomics using Bitwise AND.
-* `Abit.difference/2` - Clears bits in left atomics that are set in right using Bitwise AND NOT.
-* `Abit.symmetric_difference/2` - Symmetric difference of 2 atomics using Bitwise XOR.
-* `Abit.invert/1` - Inverts all bits in atomics using Bitwise NOT.
-* `Abit.bit_position/1` - Returns the bit's position in an atomics array.
-* `Abit.bit_at/2` - Returns the bit at a given position from atomics.
-* `Abit.set_bit_at/3` - Sets the bit in atomics at the given position to the given bit (0 or 1).
-* `Abit.toggle_bit_at/2` - Toggles the bit in atomics at the given position.
+* `Abit.bit_count/1` - Returns the total number of bits in an atomics reference.
+* `Abit.union/2` - Combines two atomics references using bitwise OR.
+* `Abit.intersect/2` - Intersects two atomics references using bitwise AND.
+* `Abit.difference/2` - Clears bits in the left-hand atomics reference that are set in the right-hand reference using bitwise AND NOT.
+* `Abit.symmetric_difference/2` - Computes the symmetric difference of two atomics references using bitwise XOR.
+* `Abit.invert/1` - Inverts all bits in an atomics reference using bitwise NOT.
+* `Abit.bit_position/1` - Returns a bit's position in an atomics array.
+* `Abit.bit_at/2` - Returns the bit at a given position in an atomics reference.
+* `Abit.set_bit_at/3` - Sets the bit at a given position in an atomics reference to 0 or 1.
+* `Abit.toggle_bit_at/2` - Toggles the bit at a given position in an atomics reference.
 * `Abit.clear/1` - Sets all elements in the atomics reference to 0.
-* `Abit.set_bits_count/1` - Returns the number of bits set to 1 in atomics.
-* `Abit.hamming_distance/2` - Returns the bitwise Hamming distance between the 2 given atomics.
-* `Abit.to_list/1` - Returns a flat list of every atomic value converted into a list of bits.
+* `Abit.set_bits_count/1` - Returns the number of bits set to 1 in an atomics reference.
+* `Abit.hamming_distance/2` - Returns the bitwise Hamming distance between two atomics references.
+* `Abit.to_list/1` - Converts every integer in an atomics reference into a flat list of bits.
 
-### Abit.Atomics - utility functions for working with Erlang's :atomics
-* `Abit.Atomics.to_list/1` - Converts an :atomics reference to a list of integers.
-* `Abit.Atomics.member?/2` - Checks if an integer is present in the :atomics reference.
-* `Abit.Atomics.serialize/1` - Serializes an :atomics reference into a binary.
-* `Abit.Atomics.deserialize/1` - Deserializes a binary into an :atomics reference.
+### Abit.Atomics - utility functions for working with Erlang's `:atomics`
+* `Abit.Atomics.to_list/1` - Converts an `:atomics` reference to a list of integers.
+* `Abit.Atomics.member?/2` - Checks whether an integer is present in an `:atomics` reference.
+* `Abit.Atomics.serialize/1` - Serializes an `:atomics` reference into a binary.
+* `Abit.Atomics.deserialize/1` - Deserializes a binary into an `:atomics` reference.
 
 ### Abit.Counter - use `:atomics` as an array of N-bit counters
 * `Abit.Counter.new/3` - Creates a new array of counters. Returns an `%Abit.Counter{}` struct.
 * `Abit.Counter.clear/1` - Sets all elements in the counter array to 0.
-* `Abit.Counter.get/2` - Returns the value of counter at the given index.
-* `Abit.Counter.put/3` - Puts the value into counter at the given index.
-* `Abit.Counter.add/3` - Adds the increment to counter at the given index.
+* `Abit.Counter.get/2` - Returns the value of the counter at the given index.
+* `Abit.Counter.put/3` - Stores a value in the counter at the given index.
+* `Abit.Counter.add/3` - Adds an increment to the counter at the given index.
 * `Abit.Counter.member?/2` - Returns `true` if any counter has the given value, `false` otherwise.
-* `Abit.Counter.get_all_at_atomic/2` - Returns all counters from atomics at a given index.
+* `Abit.Counter.get_all_at_atomic/2` - Returns all counters packed into the atomics element at the given index.
 
 ### Abit.Bitmask - helper functions for bitmasks
 * `Abit.Bitmask.set_bits_count/1` - Returns the number of bits set to 1 in the given integer.
 * `Abit.Bitmask.bit_at/2` - Returns the bit at a given position in the given integer.
 * `Abit.Bitmask.set_bit_at/3` - Sets a bit in the given integer at the given position to a given bit (0 or 1).
 * `Abit.Bitmask.toggle_bit_at/2` - Toggles the bit at a given position in the given integer.
-* `Abit.Bitmask.hamming_distance/2` - Returns the bitwise Hamming distance between the 2 given integers.
+* `Abit.Bitmask.hamming_distance/2` - Returns the bitwise Hamming distance between two integers.
 * `Abit.Bitmask.to_list/2` - Converts the given integer to a list of bits.
 
 

lib/abit.ex

@@ -57,10 +57,10 @@ defmodule Abit do
   import Bitwise
 
   @doc """
-  Returns total count of bits in atomics `ref`.
+  Returns the total number of bits in the atomics reference `ref`.
 
-  `:atomics` are 64-bit integers, so the total
-  count of bits is size * 64.
+  Each element in an atomics reference is a 64-bit integer, so the total
+  number of bits is `size * 64`.
 
   ## Examples
 
@@ -77,11 +77,9 @@ defmodule Abit do
   end
 
   @doc """
-  Union bits of atomics `ref_a` & `ref_b` using the
-  bitwise OR operator.
+  Combines the atomics references `ref_a` and `ref_b` using bitwise OR.
 
-  `ref_b` will be unioned into `ref_a`.
-  Returns `ref_a` mutated.
+  Mutates and returns `ref_a`.
   """
   @spec union(reference, reference) :: reference
   def union(ref_a, ref_b) when is_reference(ref_a) and is_reference(ref_b) do
@@ -108,9 +106,9 @@ defmodule Abit do
   end
 
   @doc """
-  Bit intersection of atomics using Bitwise AND operator.
+  Intersects the atomics references `ref_a` and `ref_b` using bitwise AND.
 
-  Returns `ref_a` mutated.
+  Mutates and returns `ref_a`.
   """
   @spec intersect(reference, reference) :: reference
   def intersect(ref_a, ref_b) when is_reference(ref_a) and is_reference(ref_b) do
@@ -130,10 +128,10 @@ defmodule Abit do
   end
 
   @doc """
-  Bit difference of atomics using Bitwise AND NOT operators.
+  Computes the difference between `ref_a` and `ref_b` using bitwise AND NOT.
 
   Clears the bits in `ref_a` that are set in `ref_b`.
-  Returns `ref_a` mutated.
+  Mutates and returns `ref_a`.
   """
   @doc since: "0.4.0"
   @spec difference(reference, reference) :: reference
@@ -154,9 +152,9 @@ defmodule Abit do
   end
 
   @doc """
-  Bit symmetric difference (XOR) of atomics using Bitwise XOR operator.
+  Computes the symmetric difference of `ref_a` and `ref_b` using bitwise XOR.
 
-  Returns `ref_a` mutated.
+  Mutates and returns `ref_a`.
   """
   @doc since: "0.4.0"
   @spec symmetric_difference(reference, reference) :: reference
@@ -177,9 +175,9 @@ defmodule Abit do
   end
 
   @doc """
-  Inverts all bits in the atomics reference using Bitwise NOT operator.
+  Inverts all bits in the atomics reference `ref` using bitwise NOT.
 
-  Returns `ref` mutated.
+  Mutates and returns `ref`.
   """
   @doc since: "0.4.0"
   @spec invert(reference) :: reference
@@ -278,7 +276,7 @@ defmodule Abit do
   @doc """
   Returns the position of a bit in `:atomics`.
 
-  Returns a 2-tuple containing:
+  Returns a two-element tuple containing:
     * `atomics_index` - the index of the integer in atomics where the bit is located
     * `bit_index` - the index of the bit in the integer
 
@@ -407,8 +405,7 @@ defmodule Abit do
   end
 
   @doc """
-  Returns a flat list of every atomic value converted
-  into a list of bits from the atomics reference `ref`.
+  Converts every integer in the atomics reference `ref` into a flat list of bits.
 
   ## Examples
       ref = :atomics.new(10, signed: false)

lib/abit/atomics.ex

@@ -6,16 +6,16 @@ defmodule Abit.Atomics do
   @doc """
   Converts an :atomics reference to a list of integers.
 
-  This function takes an :atomics reference and returns a list of integers,
-  where each integer represents the value stored in each atomic.
+  This function takes an `:atomics` reference and returns a list containing
+  the value of each element.
 
   ## Parameters
 
-    * `atomics_ref` - A reference to an :atomics array.
+    * `atomics_ref` - A reference to an `:atomics` array.
 
   ## Returns
 
-  A list of integers representing the values stored in the :atomics array.
+  A list of integers representing the values stored in the `:atomics` array.
 
   ## Examples
 
@@ -41,19 +41,19 @@ defmodule Abit.Atomics do
   end
 
   @doc """
-  Checks if an integer is present in the :atomics reference.
+  Checks whether an integer is present in the `:atomics` reference.
 
-  This function checks if the given integer exists as a value in any of the
-  atomics within the provided :atomics reference.
+  This function checks whether the given integer matches any element in the
+  provided `:atomics` reference.
 
   ## Parameters
 
-    * `atomics_ref` - A reference to an :atomics array.
+    * `atomics_ref` - A reference to an `:atomics` array.
     * `int` - The integer to search for.
 
   ## Returns
 
-  Returns `true` if the integer is found in the :atomics array, `false` otherwise.
+  Returns `true` if the integer is found in the `:atomics` array, or `false` otherwise.
 
   ## Examples
 
@@ -97,18 +97,18 @@ defmodule Abit.Atomics do
   end
 
   @doc """
-  Serializes an :atomics reference into a binary.
+  Serializes an `:atomics` reference into a binary.
 
-  This function takes an :atomics reference and returns a binary where each
-  64-bit integer in the :atomics array is encoded in big-endian format.
+  This function takes an `:atomics` reference and returns a binary in which each
+  64-bit integer is encoded in big-endian format.
 
   ## Parameters
 
-    * `atomics_ref` - A reference to an :atomics array.
+    * `atomics_ref` - A reference to an `:atomics` array.
 
   ## Returns
 
-  A binary containing the serialized :atomics data.
+  A binary containing the serialized `:atomics` data.
 
   ## Examples
 
@@ -142,18 +142,18 @@ defmodule Abit.Atomics do
   end
 
   @doc """
-  Deserializes a binary into an :atomics reference.
+  Deserializes a binary into an `:atomics` reference.
 
   This function takes a binary that was previously serialized using `serialize/1`
-  and reconstructs an :atomics reference from it.
+  and reconstructs an `:atomics` reference from it.
 
   ## Parameters
 
-    * `binary` - A binary containing the serialized :atomics data.
+    * `binary` - A binary containing the serialized `:atomics` data.
 
   ## Returns
 
-  A reference to a new :atomics array containing the deserialized data.
+  A reference to a new `:atomics` array containing the deserialized data.
 
   ## Examples
 

lib/abit/bitmask.ex

@@ -1,6 +1,6 @@
 defmodule Abit.Bitmask do
   @moduledoc """
-  Functions for working with bits & integer bitmasks.
+  Functions for working with bits and integer bitmasks.
   """
 
   import Bitwise
@@ -37,7 +37,7 @@ defmodule Abit.Bitmask do
   end
 
   @doc """
-  Returns bit at `bit_index` in the given `integer`.
+  Returns the bit at `bit_index` in the given `integer`.
 
   ## Examples
 
@@ -120,8 +120,8 @@ defmodule Abit.Bitmask do
   @doc """
   Converts the given `integer` to a list of bits.
 
-  `size` is the size of the bitstring you want the integer to be
-  converted to before creating a list from it.
+  `size` specifies the bitstring size to use before converting the integer
+  to a list.
 
   ## Examples