feat: add registry.refresh() method (#1096)

1 files changed, 64 insertions, 0 deletions

diff --git a/doc/mason.txt b/doc/mason.txt
index 1c2ba506..19eba5cd 100644
--- a/doc/mason.txt
+++ b/doc/mason.txt
@@ -124,6 +124,26 @@ keybinds which you may find in the help view by pressing `g?` when the Mason
 window is open.
 
 ==============================================================================
+REGISTRIES                                                  *mason-registries*
+
+`mason.nvim` sources package definitions from the registries it has been
+configured with (see |mason-settings|). `mason.nvim` uses the core registry,
+governed by `mason.nvim`, by default. This may be extended, or even entirely
+overridden, through additional registries, like so:
+
+>lua
+    require("mason").setup {
+        registries = {
+            "lua:my-registry",
+            "github:mason-org/mason-registry",
+        },
+    }
+<
+
+Packages are loaded from registries in the order they've been configured,
+with registries appearing first in the list having precedence.
+
+==============================================================================
 HOW TO INSTALL PACKAGES                        *mason-how-to-install-packages*
 
 You may install packages either via the command interface or via Mason's Lua
@@ -170,6 +190,13 @@ keybinds which you may find in the help view by pressing `g?` when the Mason
 window is open.
 
 ------------------------------------------------------------------------------
+UPDATE REGISTRIES                                               *:MasonUpdate*
+>vim
+:MasonUpdate
+<
+Updates all managed registries.
+
+------------------------------------------------------------------------------
 INSTALLING PACKAGES                                            *:MasonInstall*
 >vim
 :MasonInstall <package> ...
@@ -471,5 +498,42 @@ get_all_package_names()
     Returns:
         string[]
 
+                                                     *mason-registry.update()*
+update({callback})
+    Updates all managed registries.
+
+    Parameters:
+        {callback} - Callback of the signature `fun(success: boolean, updated_registries: RegistrySource[])`
+
+                                                     *mason-registry.update()*
+refresh({callback?})
+    Refreshes all registries if needed. This is a convenience wrapper around
+    |mason-registry.update()| that only updates registries if:
+        1) registries haven't been updated in a while
+        2) or, one or more registries are not installed
+
+    Runs in a blocking fashion if no {callback} is provided. Note that when
+    running in blocking fashion the entire editor is frozen, so prefer the
+    asynchronous variant unless absolutely needed.
+
+    Parameters:
+        {callback?} (optional) - Invoked when the registry has been refreshed.
+
+    Example:
+>lua
+        local registry = require("mason-registry")
+
+        -- 1. synchronous
+        registry.refresh()
+        local packages = registry.get_all_packages()
+        ...
+
+        -- 2. asynchronous
+        registry.refresh(function ()
+            local packages = registry.get_all_packages()
+            ...
+        end)
+<
+
 
 vim:tw=78:ft=help:norl:expandtab:sw=4