Add improved docs

Closes GH-63.

Reviewed-by: Christian Murphy <christian.murphy.42@gmail.com>
Reviewed-by: Merlijn Vos <merlijn@soverin.net>
Reviewed-by: Remco Haszing <remcohaszing@gmail.com>

index.js

@@ -1,3 +1,8 @@
+/**
+ * @typedef {import('./lib/index.js').UrlConfig} UrlConfig
+ * @typedef {import('./lib/index.js').Options} Options
+ */
+
 import remarkValidateLinks from './lib/index.js'
 
 export default remarkValidateLinks

lib/index.js

@@ -22,6 +22,7 @@
  * @typedef Options
  *   Configuration.
  * @property {string|false} [repository]
+ *   URL to hosted Git.
  *   If `repository` is nullish, the Git origin remote is detected.
  *   If the repository resolves to something npm understands as a Git host such
  *   as GitHub, GitLab, or Bitbucket, full URLs to that host (say,
@@ -31,14 +32,13 @@
  *   explicitly.
  * @property {string} [root]
  *   A `root` (`string?`) can also be passed, referencing the local Git root
- *   directory (the place where `.git` is).
+ *   directory (the folder that contains `.git`).
  *   If both `root` and `repository` are nullish, the Git root is detected.
- *   If `root` is not given but `repository` is, [`file.cwd`][cwd] is used.
+ *   If `root` is not given but `repository` is, `file.cwd` is used.
  * @property {UrlConfig} [urlConfig]
- *   If you’re self-hosting a Git server, you can provide URL information
- *   directly, as `urlConfig` (`Object`).
-
-
+ *   If your project is hosted on `github.com`, `gitlab.com`, or `bitbucket.org`,
+ *   this plugin can automatically detect the url configuration.
+ *   Otherwise, use `urlConfig` to specify this manually.
  */
 
 import {check} from './check/index.js'