From c340ab312b8a831c4db2d75b978e45bfd83af302 Mon Sep 17 00:00:00 2001 From: Alexandre Hamez Date: Fri, 28 Feb 2025 11:07:03 +0100 Subject: [PATCH] docs: general improvement --- CONTRIBUTING.md | 29 +++++++-------- README.md | 39 +++++++++----------- benchmark/{README.md => launch_benchmark.md} | 0 documentation/reference.md | 1 - documentation/v1_to_v2_migration.md | 8 ++-- mix.exs | 2 +- 6 files changed, 36 insertions(+), 43 deletions(-) rename benchmark/{README.md => launch_benchmark.md} (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ce3f974..f33917b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # 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 @@ -9,7 +9,7 @@ Here are some guidelines to follow and some tips when contributing to protox. - (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. diff --git a/README.md b/README.md index 40383f56..363ee34c 100644 --- a/README.md +++ b/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. diff --git a/benchmark/README.md b/benchmark/launch_benchmark.md similarity index 100% rename from benchmark/README.md rename to benchmark/launch_benchmark.md diff --git a/documentation/reference.md b/documentation/reference.md index 890e63a2..66d63d95 100644 --- a/documentation/reference.md +++ b/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. -``` diff --git a/documentation/v1_to_v2_migration.md b/documentation/v1_to_v2_migration.md index 9bbe0eed..b1ff59e5 100644 --- a/documentation/v1_to_v2_migration.md +++ b/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 diff --git a/mix.exs b/mix.exs index 9e3eba7f..c7e68174 100644 --- a/mix.exs +++ b/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