Improve the documentation (#4)

Even though this package is pretty simple and the README covers
it fairly well, packages hosted at JuliaDocs presumably
should demonstrate best practices, and there is room for being more
expansive in a "real" docs page.

Note that the doctests fail without the trailing blank space added
to docs/src/index.md.

This also fixes the coverage badge.

Author: timholy

README.md

@@ -2,7 +2,7 @@
 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaDocs.github.io/ModuleDocstrings.jl/stable)
 [![Build Status](https://github.com/JuliaDocs/ModuleDocstrings.jl/workflows/CI/badge.svg)](https://github.com/JuliaDocs/ModuleDocstrings.jl/actions)
-[![Coverage](https://codecov.io/gh/JuliaDocs/ModuleDocstrings.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaDocs/ModuleDocstrings.jl)
+[![Coverage](https://codecov.io/gh/JuliaDocs/ModuleDocstrings.jl/branch/main/graph/badge.svg?token=5Wdh1eXbGc)](https://codecov.io/gh/JuliaDocs/ModuleDocstrings.jl)
 
 A package to create simple "module docstrings" for Julia packages. These are targeted at summarizing the main components of your package, essentially as a prompt or reminder to users.  For example:
 
@@ -18,16 +18,23 @@ search: ModuleDocstrings
     •  ModuleDocstrings.write: add an API summary docstring to a package.
 ```
 
-Then, to learn more about `generate`:
+This reminds users that the two main functions are `ModuleDocstrings.generate` and `ModuleDocstrings.write`.
+
+These summaries are brief; to learn more about a particular function, read its help in full:
 
 ```julia
 help?> ModuleDocstrings.generate
   ModuleDocstrings.generate(mod::Module)
 
   Return an API summary string for mod.
 
-  The summary is assembled from all docstrings in the package, picking the
-  first sentence of each docstring. Expect to need to edit these by hand to
-  produce something truly useful.
+  The summary is assembled from all docstrings in the package, picking the first sentence of each docstring. When added to the
+  package (see ModuleDocstrings.write), you should expect to make edits by hand:
+
+    •  exclude docstrings that shouldn't appear in the API summary
 
+    •  rephrase summaries for greater clarity or compactness (alternatively, consider making such changes to the original
+       docstring)
 ```
+
+Once you've added the docstring to a `Pkg.develop`ed package, it can be submitted as a pull request.

docs/src/index.md

@@ -4,11 +4,91 @@ CurrentModule = ModuleDocstrings
 
 # ModuleDocstrings
 
-Documentation for [ModuleDocstrings](https://github.com/JuliaDocs/ModuleDocstrings.jl).
+This package aims to make it easier to attach a docstring to a module, providing users with a quick summary of the core functionality in a package.
+
+To demonstrate, let's create a module with a few docstrings. This module has two functions: `radius` with a single method,
+and `distance` with two methods (the details of the methods don't really matter much for this demonstration):
 
-```@index
+```jldoctest example
+julia> module TestDocStrings
+       
+       export radius, distance
+       
+       """
+           radius(x, y, z)
+       
+       Compute the radius of the cartesian-coordinate position `[x, y, z]`.
+       
+       There really isn't much more to say; it's pretty straightforward.
+       """
+       radius(x, y, z) = sqrt(x^2 + y^2 + z^2)
+       
+       
+       """
+           distance(pos1::AbstractVector, pos2::AbstractVector)
+       
+       Compute the distance between points `pos1` and `pos2`.
+       """
+       distance(pos1::AbstractVector, pos2::AbstractVector) = radius((pos1 - pos2)...)
+       
+       """
+           distance(pos::AbstractVector, points::PointCollection)
+       
+       Compute the minimum distance between `pos` and any point in `points`.
+       """
+       distance(pos::AbstractVector, points::AbstractVector{<:AbstractVector}) = minimum(p -> distance(pos, p), points)
+       
+       end
+TestDocStrings
 ```
 
-```@autodocs
-Modules = [ModuleDocstrings]
+Now let's generate a module doctring:
+
+```jldoctest example
+julia> using ModuleDocstrings
+
+julia> print(ModuleDocstrings.generate(TestDocStrings))
+- `distance`:
+  + Compute the minimum distance between `pos` and any point in `points`.
+  + Compute the distance between points `pos1` and `pos2`.
+- `radius`: Compute the radius of the cartesian-coordinate position `[x, y, z]`.
+```
+
+From this, you can see that both methods of `distance` are listed, as well as the single method for `radius`.
+For each, only the first sentence is used in the summary.
+
+If this were a package that you have in `Pkg.develop` mode, you could insert this string into the package with [`ModuleDocstrings.write`](@ref).  However, in this case, you get
+
+```jldoctest example; filter=(r"julia/dev/.*")
+julia> ModuleDocstrings.write(TestDocStrings)
+ERROR: TestDocStrings must be a writable package, but there is no corresponding file, suggesting it wasn't loaded from a package.
+Stacktrace:
+ [1] error(s::String)
+   @ Base ./error.jl:33
+ [2] error_write(mod::Module, #unused#::Nothing)
+   @ ModuleDocstrings ~/.julia/dev/ModuleDocstrings/src/ModuleDocstrings.jl:101
+ [3] write(mod::Module, str::String)
+   @ ModuleDocstrings ~/.julia/dev/ModuleDocstrings/src/ModuleDocstrings.jl:79
+ [4] write(mod::Module)
+   @ ModuleDocstrings ~/.julia/dev/ModuleDocstrings/src/ModuleDocstrings.jl:96
+ [5] top-level scope
+   @ none:1
+```
+
+This error ocurred because we defined the module at the REPL; it will likewise error if you have `Pkg.add`ed rather than `Pkg.develop`ed.  But for a package checked out in `develop` mode it will modify the main package file.
+
+!!! warning
+    Be sure you've saved any work *before* running `ModuleDocstrings.write`.
+
+Generally speaking, you should then edit the docstring to trim any methods that don't merit a mention in the summary, and/or to improve the clarity, brevity, or organization of the summaries.  Sometimes, you may discover that you can improve the original source docstring as well.
+
+Your changes can then be submitted as a pull request.
+
+## API
+
+Documentation for [ModuleDocstrings](https://github.com/JuliaDocs/ModuleDocstrings.jl).
+
+```@docs
+ModuleDocstrings.generate
+ModuleDocstrings.write
 ```

src/ModuleDocstrings.jl

@@ -10,7 +10,11 @@ module ModuleDocstrings
 Return an API summary string for `mod`.
 
 The summary is assembled from all docstrings in the package, picking the first sentence of each docstring.
-Expect to need to edit these by hand to produce something truly useful.
+When added to the package (see [`ModuleDocstrings.write`](@ref)), you should expect to make edits by hand:
+
+- exclude docstrings that shouldn't appear in the API summary
+- rephrase summaries for greater clarity or compactness (alternatively, consider making such changes to the
+  original docstring)
 """
 function generate(mod::Module)
     exported = Set(names(mod))