From b20a78d1fd454078668144775c4f29044e7ee624 Mon Sep 17 00:00:00 2001 From: Mathieu Barbin Date: Thu, 22 Aug 2024 11:10:51 +0200 Subject: [PATCH] Unwrap doc text --- doc/docs/design/introduction.md | 2 +- doc/docs/design/traits.md | 28 ++++++---------------------- example/README.md | 13 ++++--------- test/cram/README.md | 29 ++++++++--------------------- test/expect/README.md | 6 ++---- 5 files changed, 21 insertions(+), 57 deletions(-) diff --git a/doc/docs/design/introduction.md b/doc/docs/design/introduction.md index 90281b4..b739cfc 100644 --- a/doc/docs/design/introduction.md +++ b/doc/docs/design/introduction.md @@ -6,7 +6,7 @@ The concurrency runtime must be compatible with programs written in a direct sty ## How It Works -`Vcs` is an interface composed of [Traits](./traits.md), each providing different functionalities associated with Git interaction. The dynamic dispatch implementation of Vcs is powered by the [provider](https://github.com/mbarbin/provider) library. +`Vcs` is an interface composed of [Traits](./traits.md), each providing different functionalities associated with Git operations. The dynamic dispatch implementation of Vcs is powered by the [provider](https://github.com/mbarbin/provider) library. ## Architecture diff --git a/doc/docs/design/traits.md b/doc/docs/design/traits.md index bf5bcb5..ac2adf2 100644 --- a/doc/docs/design/traits.md +++ b/doc/docs/design/traits.md @@ -1,33 +1,17 @@ # The Power of Traits in `Vcs` -The `Vcs` library leverages the `provider`-based parametric model to offer a -flexible and adaptable interface for Git interaction. This model, also used in -the `Eio` library (`Eio.Resource`), allows us to define small scopes of -functionality, or `Traits`, within the `Vcs` library. +The `Vcs` library leverages the `provider`-based parametric model to offer a flexible and adaptable interface for Git operations. This model, also used in the `Eio` library (`Eio.Resource`), allows us to define small scopes of functionality, or `Traits`, within the `Vcs` library. ## Experience with `providers` -Our use of the [provider](https://github.com/mbarbin/provider) based parametric -library in `Vcs` serves as a practical, real-world case study of this pattern. +Our use of the [provider](https://github.com/mbarbin/provider) based parametric library in `Vcs` serves as a practical, real-world case study of this pattern. -We aim to bring this pattern to the attention of the community, fostering a -general understanding that can be applied to other projects using the same -pattern. In essence, understanding the parametrized model of `Vcs` equates to -understanding `Eio.Resource`, and vice versa. +We aim to bring this pattern to the attention of the community, fostering a general understanding that can be applied to other projects using the same pattern. In essence, understanding the parametrized model of `Vcs` equates to understanding `Eio.Resource`, and vice versa. ## Granularity of the Interface via Trait Granularity -The `Trait` design of `provider` allows us to define specific and isolated -sub-functionalities within the `Vcs` library. This granularity enables different -providers to choose which `Trait` they wish to implement, offering a level of -flexibility not possible with a monolithic functor. +The `Trait` design of `provider` allows us to define specific and isolated sub-functionalities within the `Vcs` library. This granularity enables different providers to choose which `Trait` they wish to implement, offering a level of flexibility not possible with a monolithic functor. -With `Traits`, you can select a provider with the specific set of traits you -need, without changing any other code. As explained -[here](https://mbarbin.github.io/provider/provider/Provider/Interface/index.html#type-t), -provider interfaces come with some notion of phantom types, offering additional -compiler assistance. +With `Traits`, you can select a provider with the specific set of traits you need, without changing any other code. As explained [here](https://mbarbin.github.io/provider/provider/Provider/Interface/index.html#type-t), provider interfaces come with some notion of phantom types, offering additional compiler assistance. -In summary, the use of `Traits` in `Vcs` provides a flexible, adaptable, and -granular interface for Git interaction, promoting a broader understanding and -application of the `provider`-based parametric model. +In summary, the use of `Traits` in `Vcs` provides a flexible, adaptable, and granular interface for Git operations, promoting a broader understanding and application of the `provider`-based parametric model. diff --git a/example/README.md b/example/README.md index 9e552d8..c5a83b7 100644 --- a/example/README.md +++ b/example/README.md @@ -1,18 +1,13 @@ # Vcs examples -In this directory we include some examples to illustrate how using `Vcs` looks -like. +In this directory we include some examples to illustrate how using `Vcs` looks like. -Since there are several providers available (`Eio`, `Blocking`), we decided to -select one main provider that most examples will use. We selected `Eio` for this. +Since there are several providers available (`Eio`, `Blocking`), we decided to select one main provider that most examples will use. We selected `Eio` for this. The intended entry point to browse these examples is `hello_vcs.ml`. -You can still have a look at `hello_blocking.ml` for an example showing how to -use the blocking interface of vcs. +You can still have a look at `hello_blocking.ml` for an example showing how to use the blocking interface of vcs. -The examples in this directory are not meant to be exhaustive, or replace the -tests that we have in other places in the repository. Rather they are intended -to give you a quick feel for what's `Vcs` and how to use it. +The examples in this directory are not meant to be exhaustive, or replace the tests that we have in other places in the repository. Rather they are intended to give you a quick feel for what's `Vcs` and how to use it. Welcome to Vcs' examples, and happy Giting! diff --git a/test/cram/README.md b/test/cram/README.md index 4c645eb..04c228f 100644 --- a/test/cram/README.md +++ b/test/cram/README.md @@ -2,24 +2,17 @@ ## Motivation -In this directory, we test the command line `ocaml-vcs`. This command line is -itself motivated by the desire to run exploratory tests using the vcs interface -and the git backend available on actual repositories. +In this directory, we test the command line `ocaml-vcs`. This command line is itself motivated by the desire to run exploratory tests using the vcs interface and the git backend available on actual repositories. -What we aim for these tests is to make sure `vcs` is not broken in some ways, -thus we would like to have good coverage of the commands it exposes. +What we aim for in these tests is to make sure that `ocaml-vcs` is not broken in some ways, thus we would like to have good coverage of the commands it exposes. -This is not a test for `git` itself, and to the extent possible, the tests in -this directory shall try to make little direct calls to git commands. Prefer -minting a new `vcs` command that does what you need instead. +This is not a test for `git` itself, and to the extent possible, the tests in this directory shall try to make little direct calls to git commands. Prefer minting a new `vcs` command that does what you need instead. ## Testing environment ### Limiting GitHub specifics -In the testing environment of GitHub workflow actions, it is necessary to take -some extra steps to make the test work. We prefer not to rely on a solution -involving using the config of the workflow itself, such as: +In the testing environment of GitHub workflow actions, it is necessary to take some extra steps to make the test work. We prefer not to rely on a solution involving using the config of the workflow itself, such as: ```yaml steps: @@ -32,15 +25,11 @@ steps: # Your test commands here ``` -The reason is because we'd also would like the tests to work when run with -`dune` locally during development, and we prefer to limit special logic we have -dedicated to the GitHub environment to a minimum and rather find ways to take -steps that are applicable to all testing environments in use. +The reason is because we'd also would like the tests to work when run with `dune` locally during development, and we prefer to limit special logic we have dedicated to the GitHub environment to a minimum and rather find ways to take steps that are applicable to all testing environments in use. ### Initialize git config -It is necessary to set some git config values. This may be done locally to the -repo under test. +It is necessary to set some git config values. This may be done locally to the repo under test. In the cram tests we'll do: @@ -73,12 +62,10 @@ Or the equivalent in `vcs`: $ ocaml-vcs rename-current-branch main ``` -Note that it is not possible to run the following in the GitHub workflow actions -before `git init` (this results in an error). +Note that it is not possible to run the following in the GitHub workflow actions before `git init` (this results in an error). ```sh $ git config init.defaultBranch ``` -And we do not want to make use of the `--global` for the reasons explained in -the GitHub specifics part. \ No newline at end of file +And we do not want to make use of the `--global` for the reasons explained in the GitHub specifics part. diff --git a/test/expect/README.md b/test/expect/README.md index 5208d05..97d10cf 100644 --- a/test/expect/README.md +++ b/test/expect/README.md @@ -1,7 +1,5 @@ # Vcs expect tests -This directory contains functional tests for `Vcs` that combine functionalities -from different libraries. +This directory contains unit and functional tests for `Vcs` that combine functionalities from different libraries. -They can be a useful addition to the dedicated unit tests located within each -library's directory. +They can be a useful addition to the dedicated unit tests located within each library's directory.