Informative error for un-devved packages (#3)

Modules defined at the REPL or packages being used in `add` mode
are not amenable to updates. Rather than throw a cryptic error
it's better to suggest the solution.

Also adds a test that `write` works.

Author: timholy

Project.toml

@@ -7,7 +7,9 @@ version = "0.1.0"
 julia = "1.3"
 
 [extras]
+Example = "7876af07-990d-54b4-ab0e-23690620f79a"
+Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test"]
+test = ["Example", "Pkg", "Test"]

src/ModuleDocstrings.jl

@@ -72,6 +72,7 @@ The package should be checked out in `develop` mode before calling `write`.
 """
 function write(mod::Module, str)
     path = pathof(mod)
+    (path === nothing || !iswritable(path)) && error_write(mod, path)
     modstr = read(path, String)
     idxs = findfirst("module $mod", modstr)
     idxs === nothing && error("could not identify start of module")
@@ -90,4 +91,10 @@ The package should be checked out in `develop` mode before calling `write`.
 """
 write(mod::Module) = write(mod, generate(mod))
 
+# this is replacing, not extending, the Base function of the same name
+iswritable(filename::AbstractString) = isfile(filename) && (uperm(filename) & 0x02) != 0x00
+
+error_write(mod, ::Nothing) = error("$mod must be a writable package, but there is no corresponding file, suggesting it wasn't loaded from a package.")
+error_write(mod, path::AbstractString) = error("$mod must be a writable package, but the path \"$path\" is not writable.\nDid you forget to `Pkg.develop` the package?")
+
 end

test/runtests.jl

@@ -1,12 +1,14 @@
 using ModuleDocstrings
+using Example   # test error on a non-devved package
+using Pkg
 using Test
 
 @testset "ModuleDocstrings.jl" begin
     str = ModuleDocstrings.generate(ModuleDocstrings)
     @test occursin("ModuleDocstrings.generate", str)
     @test occursin("ModuleDocstrings.write", str)
 
-    str = ModuleDocstrings.generate(@eval Module() begin
+    m = @eval Module() begin
         """
             foo1()
 
@@ -27,8 +29,49 @@ using Test
         foo3()
 
         @__MODULE__
-    end)
+    end
+    str = ModuleDocstrings.generate(m)
     @test occursin("- `Main.anonymous.foo1`: `foo1` is pretty useful.", str)
     @test occursin("- `Main.anonymous.foo2`: `foo2` doesn't show the signature.", str)
     @test occursin("- `Main.anonymous.foo3`: `foo3` contains a [`Main.anonymous.foo1`](@ref) that contains a period.", str)
+
+    if Base.VERSION >= v"1.8.0-DEV.363"   # use strings in @test_throws; we don't care what type of error this is
+        @test_throws "must be a writable package, but there is no corresponding file" ModuleDocstrings.write(m)
+        @test_throws r"must be a writable package, but the path \".*\" is not writable" ModuleDocstrings.write(Example)
+    else
+        @test_throws Exception ModuleDocstrings.write(m)
+        @test_throws Exception ModuleDocstrings.write(Example)
+    end
+
+    mktempdir() do pkgs
+        push!(LOAD_PATH, pkgs)
+        newpkgdir = joinpath(pkgs, "DevDummy")
+        Pkg.generate(newpkgdir)
+        open(joinpath(newpkgdir, "src", "DevDummy.jl"), "w") do io
+            print(io,
+"""
+module DevDummy
+
+\"\"\"
+    greet()
+
+Print a delightful greeting.
+\"\"\"
+greet() = print("Hello World!")
+
+end # module
+"""
+            )
+        end
+        @eval using DevDummy
+        ModuleDocstrings.write(DevDummy)
+        str = read(joinpath(newpkgdir, "src", "DevDummy.jl"), String)
+        @test occursin(
+"""
+\"\"\"
+- `DevDummy.greet`: Print a delightful greeting.
+\"\"\"
+module DevDummy
+""", str)
+    end
 end