From 39ea593b353a6e77b18dfaf42343dc320e270436 Mon Sep 17 00:00:00 2001
From: Gilles Peiffer <gilles.peiffer@outlook.com>
Date: Sun, 8 Sep 2019 18:12:03 +0200
Subject: [PATCH] Update README to better represent the reason for having this
 package

---
 README.md | 26 ++++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index b6a411a..86a815f 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,28 @@
-# MutableArithmetics
+# MutableArithmetics.jl
 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaOpt.github.io/MutableArithmetics.jl/stable)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaOpt.github.io/MutableArithmetics.jl/dev)
 [![Build Status](https://travis-ci.com/JuliaOpt/MutableArithmetics.jl.svg?branch=master)](https://travis-ci.com/JuliaOpt/MutableArithmetics.jl)
 [![Build Status](https://ci.appveyor.com/api/projects/status/github/JuliaOpt/MutableArithmetics.jl?svg=true)](https://ci.appveyor.com/project/JuliaOpt/MutableArithmetics-jl)
 [![Codecov](https://codecov.io/gh/JuliaOpt/MutableArithmetics.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaOpt/MutableArithmetics.jl)
-[![Coveralls](https://coveralls.io/repos/github/JuliaOpt/MutableArithmetics.jl/badge.svg?branch=master)](https://coveralls.io/github/JuliaOpt/MutableArithmetics.jl?branch=master)
-[![Build Status](https://api.cirrus-ci.com/github/JuliaOpt/MutableArithmetics.jl.svg)](https://cirrus-ci.com/github/JuliaOpt/MutableArithmetics.jl)/MutableArithmetics.jl)
+[![Coverage Status](https://coveralls.io/repos/github/JuliaOpt/MutableArithmetics.jl/badge.svg?branch=master)](https://coveralls.io/github/JuliaOpt/MutableArithmetics.jl?branch=master)
+[![Build Status](https://api.cirrus-ci.com/github/JuliaOpt/MutableArithmetics.jl.svg)](https://cirrus-ci.com/github/JuliaOpt/MutableArithmetics.jl)
+
+**MutableArithmetics** is a [Julia](http://julialang.org) package which allows:
+*   for mutable types to implement mutable arithmetics;
+*   for algorithms that could exploit mutable arithmetics to exploit them while still being completely generic.
+
+While in some cases, similar features have been included in packages
+idiosyncratically, the goal of this package is to provide a generic interface to
+ allow anyone to make use of mutability when desired.
+
+The package allows users to indicate when a mutable implementation of a certain
+method is available through the use of so-called *traits*, as well as providing
+a simple way forusers to make operations fall back to these implementations.
+Examples of implementations of this interface are given in the `examples`
+folder.
+
+## Quick Example & Benchmark
 
 ```julia
 using BenchmarkTools
@@ -41,7 +57,9 @@ MA.mutability(::Type{BigInt}, ::typeof(MA.add_to!), ::Type{BigInt}, ::Type{BigIn
 MA.add_to_impl!(x::BigInt, a::BigInt, b::BigInt) = Base.GMP.MPZ.add!(x, a, b)
 MA.muladd_buf_impl!(buf::BigInt, a::BigInt, b::BigInt, c::BigInt) = Base.GMP.MPZ.add!(a, Base.GMP.MPZ.mul!(buf, b, c))
 
-println("MA performance after definining interface: ")
+println("MA performance after defining the MA interface: ")
 trial2 = @benchmark MA.mul_to!($c2, $A2, $b2)
 display(trial2)
 ```
+
+> This package started out as a GSoC '19 project.