Some improvements (#1)

* Update docstring according to Julia style guide
* Clean InverseFunctions.jl
* Simplify CI
* Update src/inverse.jl

Author: devmotion

.github/workflows/ci.yml

@@ -4,11 +4,14 @@ on:
   push:
     branches:
       - master
-      - dev
-      - 'releases/**'
     tags: '*'
   pull_request:
-  release:
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
 
 jobs:
   test:
@@ -24,19 +27,18 @@ jobs:
           - 'nightly'
         os:
           - ubuntu-latest
-          - macOS-latest
-          - windows-latest
         arch:
           - x64
-          - x86
-        exclude:
-          # 32-bit Julia binaries are not available on macOS
-          - os: macOS-latest
-            arch: x86
-          - os: windows-latest
-            arch: x86
-          - version: nightly
+        include:
+          - version: 1
+            os: ubuntu-latest
             arch: x86
+          - version: 1
+            os: macOS-latest
+            arch: x64
+          - version: 1
+            os: windows-latest
+            arch: x64
     steps:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@latest
@@ -55,11 +57,13 @@ jobs:
             ${{ runner.os }}-test-
             ${{ runner.os }}-
       - uses: julia-actions/julia-buildpkg@latest
-        env:
-          PYTHON: 'Conda'
       - uses: julia-actions/julia-runtest@latest
+        with:
+          coverage: ${{ matrix.version == '1' && matrix.os == 'ubuntu-latest' && matrix.arch == 'x64' }}
       - uses: julia-actions/julia-processcoverage@v1
+        if: matrix.version == '1' && matrix.os == 'ubuntu-latest' && matrix.arch == 'x64'
       - uses: codecov/codecov-action@v1
+        if: matrix.version == '1' && matrix.os == 'ubuntu-latest' && matrix.arch == 'x64'
         with:
           file: lcov.info
   docs:
@@ -82,8 +86,6 @@ jobs:
             ${{ runner.os }}-test-
             ${{ runner.os }}-
       - uses: julia-actions/julia-buildpkg@latest
-        env:
-          PYTHON: 'Conda'
       - uses: julia-actions/julia-docdeploy@latest
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Project.toml

@@ -8,7 +8,8 @@ version = "0.1.0"
 julia = "1"
 
 [extras]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test"]
+test = ["Documenter", "Test"]

docs/make.jl

@@ -7,6 +7,14 @@
 using Documenter
 using InverseFunctions
 
+# Doctest setup
+DocMeta.setdocmeta!(
+    InverseFunctions,
+    :DocTestSetup,
+    :(using InverseFunctions);
+    recursive=true,
+)
+
 makedocs(
     sitename = "InverseFunctions",
     modules = [InverseFunctions],

src/InverseFunctions.jl

@@ -1,7 +1,4 @@
 # This file is a part of InverseFunctions.jl, licensed under the MIT License (MIT).
-
-__precompile__(true)
-
 """
     InverseFunctions
 

src/inverse.jl

@@ -1,48 +1,54 @@
 # This file is a part of InverseFunctions.jl, licensed under the MIT License (MIT).
 
-
 """
     inverse(f)
 
-Returns the inverse of a function `f`.
+Return the inverse of function `f`.
+
+`inverse` supports mapped and broadcasted functions (via `Base.Fix1`) and
+function composition (requires Julia >= 1.6).
+
+# Examples
+
+```jldoctest
+julia> foo(x) = inv(exp(-x) + 1);
+
+julia> inv_foo(y) = log(y / (1 - y));
 
-The following conditions must be satisfied:
+julia> InverseFunctions.inverse(::typeof(foo)) = inv_foo;
 
-* `inverse(f) ∘ f` must be equivalent to `identity`.
-* `inverse(f)(f(x)) ≈ x`
-* `inverse(inverse(f))` must be equivalent (ideally identical) to `f`.
+julia> InverseFunctions.inverse(::typeof(inv_foo)) = foo;
 
-`inverse` supports mapped/broadcasted functions (via `Base.Fix1`) and (on
-Julia >=v1.6) function composition.
+julia> x = 4.2;
 
+julia> inverse(foo)(foo(x)) ≈ x
+true
 
-Example:
+julia> inverse(inverse(foo)) === foo
+true
 
-```julia
-foo(x) = inv(exp(-x) + 1)
-inv_foo(y) = log(y / (1 - y))
+julia> broadcast_foo = Base.Fix1(broadcast, foo);
 
-InverseFunctions.inverse(::typeof(foo)) = inv_foo
-InverseFunctions.inverse(::typeof(inv_foo)) = foo
+julia> X = rand(10);
 
-x = 4.2
-@assert inverse(foo)(foo(x)) ≈ x
-@assert inverse(inverse(foo)) == foo
+julia> inverse(broadcast_foo)(broadcast_foo(X)) ≈ X
+true
 
-X = rand(10)
-broadcasted_foo = Base.Fix1(broadcast, foo)
-Y = broadcasted_foo(X)
-@assert inverse(broadcasted_foo)(Y) ≈ X
+julia> bar = log ∘ foo;
 
-# Requires Julia >= v1.6:
-bar = log ∘ foo
-@assert inverse(bar)(bar(x)) ≈ x
+julia> VERSION < v"1.6" || inverse(bar)(bar(x)) ≈ x
+true
 ```
+
+# Implementation
+
+Implementations of `inverse(::typeof(f))` have to satisfy
+* `inverse(f)(f(x)) ≈ x` for all `x` in the domain of `f`, and
+* `inverse(inverse(f)) === f`.
 """
-function inverse end
+inverse(f)
 export inverse
 
-
 inverse(::typeof(inverse)) = inverse
 
 @static if VERSION >= v"1.6"
@@ -56,7 +62,6 @@ inverse(::typeof(inv)) = inv
 inverse(::typeof(adjoint)) = adjoint
 inverse(::typeof(transpose)) = transpose
 
-
 inverse(::typeof(exp)) = log
 inverse(::typeof(log)) = exp
 

test/runtests.jl

@@ -1,7 +1,18 @@
 # This file is a part of InverseFunctions.jl, licensed under the MIT License (MIT).
 
-import Test
+using InverseFunctions
+using Documenter
+using Test
 
-Test.@testset "Package InverseFunctions" begin
+@testset "Package InverseFunctions" begin
     include("test_inverse.jl")
+
+    # doctests
+    DocMeta.setdocmeta!(
+        InverseFunctions,
+        :DocTestSetup,
+        :(using InverseFunctions);
+        recursive=true,
+    )
+    doctest(InverseFunctions)
 end # testset

test/test_inverse.jl

@@ -1,9 +1,5 @@
 # This file is a part of InverseFunctions.jl, licensed under the MIT License (MIT).
 
-using InverseFunctions
-using Test
-
-
 foo(x) = inv(exp(-x) + 1)
 inv_foo(y) = log(y / (1 - y))