docs: general improvement

CONTRIBUTING.md

@@ -1,15 +1,15 @@
 # How to contribute to protox
 First, thank you for your interest in contributing to protox!
 
-Here are some guidelines to follow and some tips when contributing to protox.
+To ensure a smooth experience while contributing, here are a few handy guidelines.
 
 ## Development Prerequisites
 - Erlang/OTP 26 or later
 - Elixir 1.15 or later
 - (optional) [lefthook](https://evilmartians.github.io/lefthook/installation) for git hooks
 
 ## Development Guidelines
-To enforce consistent code style and quality, we use the following tools:
+We use a few tools to keep the code clean and consistent:
 - [`mix deps.unlock --check-unused`](https://hexdocs.pm/mix/Mix.Tasks.Deps.Unlock.html) to check for unused dependencies
 - [`mix format --check-formatted`](https://hexdocs.pm/mix/Mix.Tasks.Format.html) to check for code formatting issues
 - [`mix credo`](https://hexdocs.pm/credo/Mix.Tasks.Credo.html) for code style and consistency checks
@@ -27,24 +27,21 @@ To enforce consistent code style and quality, we use the following tools:
 
 > [!NOTE]
 >
-> `mix test --include conformance` automatically downloads and compilesthe conformance test suite and runs it against the current version of protox.
+> `mix test --include conformance` automatically downloads and compiles the conformance test suite and runs it against the current version of protox.
 
 ### Testing
-- Add tests for any new features or bug fixes.
-- Ensure all tests pass with `mix test --include conformance`.
-- Try to maintain or improve test coverage (check with `mix test --cover`).
+Correctness is the main goal of Protox, here's how you can contribute to it:
+- add tests for any new features;
+- when fixing a bug, add tests that reproduce the bug;
+- ensure all tests pass with `mix test --include conformance`;
+- try to maintain or improve test coverage (check with `mix test --cover`).
 
 ### Documentation
-- Document public functions using ExDoc format.
-- Update module documentation when needed.
-- If possible, include examples in documentation.
-- Update README.md if needed.
-
-## Pull Request Process
-Submit a Pull Request with:
-- Clear description of changes
-- Reference to any related issues
-- Examples of new functionality if applicable
+Documentation is as important as correctness, here's a quick reminder of the things to keep in mind:
+- document public functions;
+- update module documentation if needed;
+- if possible, include examples as [doctests](https://hexdocs.pm/ex_unit/ExUnit.DocTest.html);
+- update the main [README.md](./README.md) if needed.
 
 ## License
 By contributing to Protox, you agree that your contributions will be licensed under MIT License.

README.md

@@ -2,8 +2,10 @@
 
 [![Elixir CI](https://github.com/ahamez/protox/actions/workflows/elixir.yml/badge.svg)](https://github.com/ahamez/protox/actions/workflows/elixir.yml) [![Coverage Status](https://coveralls.io/repos/github/ahamez/protox/badge.svg?branch=master)](https://coveralls.io/github/ahamez/protox?branch=master) [![Hex.pm Version](http://img.shields.io/hexpm/v/protox.svg)](https://hex.pm/packages/protox) [![Hex Docs](https://img.shields.io/badge/hex-docs-brightgreen.svg)](https://hexdocs.pm/protox/) [![License](https://img.shields.io/hexpm/l/protox.svg)](https://github.com/ahamez/protox/blob/master/LICENSE)
 
-Protox is an Elixir library for working with [Google's Protocol Buffers](https://developers.google.com/protocol-buffers), versions 2 and 3, supporting
-binary encoding and decoding.
+Protox is an Elixir library for working with [Google's Protocol Buffers](https://developers.google.com/protocol-buffers), versions 2 and 3, supporting binary encoding and decoding.
+
+The primary objective of Protox is **reliability**: it uses [property testing](https://github.com/alfert/propcheck), [mutation testing](https://github.com/devonestes/muzak) and has a [near 100% code coverage](https://coveralls.io/github/ahamez/protox?branch=master). Protox [passes all the tests](#conformance) of the conformance checker provided by Google.
+
 
 > [!NOTE]
 > If you're using version 1, please see how to migrate to version 2 [here](documentation/v1_to_v2_migration.md).
@@ -27,10 +29,6 @@ iex> binary = # read binary from a socket, a file, etc.
 iex> {:ok, msg} = Msg.decode(binary)
 ```
 
-## Reliability
-
-The primary objective of Protox is **reliability**: it uses [property testing](https://github.com/alfert/propcheck), [mutation testing](https://github.com/devonestes/muzak) and has a [near 100% code coverage](https://coveralls.io/github/ahamez/protox?branch=master). Protox [passes all the tests](#conformance) of the conformance checker provided by Google.
-
 ## Usage
 
 You can use Protox in two ways:
@@ -111,7 +109,7 @@ end
 
 ## Encode
 
-Here's how to create and encode a new message to binary protobuf:
+Here's how to encode a message to binary protobuf:
 
 ```elixir
 msg = %Foo{a: 3, b: %{1 => %Baz{}}}
@@ -197,7 +195,7 @@ msg = %Bar.Abc.Msg{a: 42}
 
 ## Specify include path
 
-An include path can be specified using the `:paths` option that specify the directories in which to search for imports:
+One or more include paths (directories in which to search for imports) can be specified using the `:paths` option:
 
 ```elixir
 defmodule Baz do
@@ -263,7 +261,7 @@ iex> Msg.unknown_fields(msg)
 [{5, 2, <<121, 97, 121, 101>>}]
 ```
 
-You must use `unknown_fields/1` as the name of the field (e.g. `__uf__` in the above example) is generated at compile-time to avoid collision with the actual fields of the Protobuf message. This function returns a list of tuples `{tag, wire_type, bytes}`. For more information, please see [protobuf encoding guide](https://developers.google.com/protocol-buffers/docs/encoding).
+You must use `unknown_fields/1` as the name of the field (e.g. `__uf__` in the above example) is generated at compile-time to avoid collision with the actual fields of the Protobuf message. This function returns a list of tuples `{tag, wire_type, bytes}`. For more information, please see the [protobuf encoding guide](https://developers.google.com/protocol-buffers/docs/encoding).
 
 > [!NOTE]
 > Unknown fields are retained when re-encoding the message.
@@ -315,12 +313,11 @@ You must use `unknown_fields/1` as the name of the field (e.g. `__uf__` in the a
       """
     end
 
-    iex> Foo.default(:a)
-    {:ok, 42}
-
     iex> %Foo{}.a
     nil
 
+    iex> Foo.default(:a)
+    {:ok, 42}
     ```
 
 * (__Protobuf 3__) __Unset fields__ are assigned to their [default values](https://developers.google.com/protocol-buffers/docs/proto3#default). However, if you use the `optional` keyword (available in protoc >= 3.15), then unset fields are assigned `nil`:
@@ -337,17 +334,17 @@ You must use `unknown_fields/1` as the name of the field (e.g. `__uf__` in the a
       """
     end
 
-    iex> Foo.default(:a)
-    {:ok, 0}
-
     iex> %Foo{}.a
     0
 
-    iex> Foo.default(:b)
-    {:error, :no_default_value}
+    iex> Foo.default(:a)
+    {:ok, 0}
 
     iex> %Foo{}.b
     nil
+
+    iex> Foo.default(:b)
+    {:error, :no_default_value}
     ```
 
 * __Messages and enums names__ are converted using the [`Macro.camelize/1`](https://hexdocs.pm/elixir/Macro.html#camelize/1) function.
@@ -376,8 +373,8 @@ You must use `unknown_fields/1` as the name of the field (e.g. `__uf__` in the a
 
 ## Generated code reference and types mapping
 
-- The detailed reference of the generated code is available [here](documentation/reference.md).
-- Please see [reference/types_mapping.md](reference/types_mapping.md) to see how protobuf types are mapped to Elixir types.
+- The detailed reference of the generated code is available in [documentation/reference.md](documentation/reference.md).
+- Please see [documentation/types_mapping.md](documentation/types_mapping.md) to see how protobuf types are mapped to Elixir types.
 
 
 ## Conformance
@@ -406,8 +403,8 @@ To launch these conformance tests, use the `protox.conformance` mix task:
 
 ## Benchmark
 
-Please see [benchmark/README.md](benchmark/README.md) for more information on how to launch benchmark.
+Please see [benchmark/launch_benchmark.md](benchmark/launch_benchmark.md) for more information on how to launch benchmark.
 
 ## Contributing
 
-Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to contribute.
+Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for more information on how to contribute.

documentation/reference.md

@@ -106,4 +106,3 @@ Get the enum entry of an integer value. If `value` does not correpond to any ent
 constants()
 ```
 Get the list of all the constants of the enum that correponds to the module on which this function has been called.
-```

documentation/v1_to_v2_migration.md

@@ -1,4 +1,4 @@
-# Migration Guide
+# Migration guide (v1 to v2)
 
 This guide explains how to migrate from version 1 to version 2 of Protox.
 
@@ -18,11 +18,11 @@ iex> msg = %Foo{a: 3, b: %{1 => %Baz{}}}
 
 It's no longer possible to encode or decode JSON data directly using Protox. If it's necessary, you can stick to version 1.7 or switch to [`protobuf`](https://hex.pm/packages/protobuf).
 
-## `Protox` options
+## `Protox` macro options
 
 The `:path` option is removed in favor of the already existing `:paths` option, thus one just has to provide a list containing a single path.
 
-Also, the `:keep_unknown_fields` option is no longer available. Thus, unknown fields are always kept. If you don't need them, you juste have to ignore them.
+Also, the `:keep_unknown_fields` option is no longer available. Thus, unknown fields are always kept. If you don't need them, you can simply ignore them.
 
 ## Generated code
 
@@ -34,7 +34,7 @@ The following functions generated for messages are replaced by the function `sch
 - `required_fields/0`
 - `syntax/0`
 
-`schema/0` returns a `%Protox.MessageSchema{}` struct which contains information about the message's fields, syntax, and file options.
+`schema/0` returns a `Protox.MessageSchema` struct which contains information about the message's fields, syntax, and file options.
 
 ### Example
 

mix.exs

@@ -108,7 +108,7 @@ defmodule Protox.Mixfile do
   defp docs() do
     [
       main: "readme",
-      extras: ["README.md", "documentation/reference.md"]
+      extras: Path.wildcard("./*.md") ++ Path.wildcard("./benchmark/*.md") ++ Path.wildcard("./documentation/*.md")
     ]
   end
 end