From a6f82d65df9f3bc95fd34805e93cefdf7f6acfa5 Mon Sep 17 00:00:00 2001
From: Katharine Hyatt <khyatt@flatironinstitute.org>
Date: Sun, 2 Sep 2018 14:51:45 -0400
Subject: [PATCH] Some more examples/formatting/xrefs for Distributed docs

---
 stdlib/Distributed/src/cluster.jl | 86 +++++++++++++++++++++++++++----
 1 file changed, 77 insertions(+), 9 deletions(-)

diff --git a/stdlib/Distributed/src/cluster.jl b/stdlib/Distributed/src/cluster.jl
index 49df11b6eef0d..e1d4bae511d91 100644
--- a/stdlib/Distributed/src/cluster.jl
+++ b/stdlib/Distributed/src/cluster.jl
@@ -720,6 +720,15 @@ const map_del_wrkr = Set{Int}()
     myid()
 
 Get the id of the current process.
+
+# Examples
+```julia-repl
+julia> myid()
+1
+
+julia> remotecall_fetch(() -> myid(), 4)
+4
+```
 """
 myid() = LPROC.id
 
@@ -727,6 +736,17 @@ myid() = LPROC.id
     nprocs()
 
 Get the number of available processes.
+
+# Examples
+```julia-repl
+julia> nprocs()
+3
+
+julia> workers()
+5-element Array{Int64,1}:
+ 2
+ 3
+```
 """
 function nprocs()
     if myid() == 1 || (PGRP.topology == :all_to_all && !isclusterlazy())
@@ -746,8 +766,19 @@ end
 """
     nworkers()
 
-Get the number of available worker processes. This is one less than `nprocs()`. Equal to
+Get the number of available worker processes. This is one less than [`nprocs()`](@ref). Equal to
 `nprocs()` if `nprocs() == 1`.
+
+# Examples
+```julia-repl
+\$ julia -p 5
+
+julia> nprocs()
+6
+
+julia> nworkers()
+5
+```
 """
 function nworkers()
     n = nprocs()
@@ -757,7 +788,18 @@ end
 """
     procs()
 
-Return a list of all process identifiers.
+Return a list of all process identifiers, including pid 1 (which is not included by [`workers()`](@ref)).
+
+# Examples
+```julia-repl
+\$ julia -p 5
+
+julia> procs()
+3-element Array{Int64,1}:
+ 1
+ 2
+ 3
+```
 """
 function procs()
     if myid() == 1 || (PGRP.topology == :all_to_all  && !isclusterlazy())
@@ -809,6 +851,16 @@ end
     workers()
 
 Return a list of all worker process identifiers.
+
+# Examples
+```julia-repl
+\$ julia -p 5
+
+julia> workers()
+2-element Array{Int64,1}:
+ 2
+ 3
+```
 """
 function workers()
     allp = procs()
@@ -832,13 +884,29 @@ Remove the specified workers. Note that only process 1 can add or remove
 workers.
 
 Argument `waitfor` specifies how long to wait for the workers to shut down:
-    - If unspecified, `rmprocs` will wait until all requested `pids` are removed.
-    - An `ErrorException` is raised if all workers cannot be terminated before
-      the requested `waitfor` seconds.
-    - With a `waitfor` value of 0, the call returns immediately with the workers
-      scheduled for removal in a different task. The scheduled `Task` object is
-      returned. The user should call `wait` on the task before invoking any other
-      parallel calls.
+  - If unspecified, `rmprocs` will wait until all requested `pids` are removed.
+  - An [`ErrorException`](@ref) is raised if all workers cannot be terminated before
+    the requested `waitfor` seconds.
+  - With a `waitfor` value of 0, the call returns immediately with the workers
+    scheduled for removal in a different task. The scheduled [`Task`](@ref) object is
+    returned. The user should call [`wait`](@ref) on the task before invoking any other
+    parallel calls.
+
+# Examples
+```julia-repl
+\$ julia -p 5
+
+julia> t = rmprocs(2, 3, waitfor=0)
+Task (runnable) @0x0000000107c718d0
+
+julia> wait(t)
+
+julia> workers()
+3-element Array{Int64,1}:
+ 4
+ 5
+ 6
+```
 """
 function rmprocs(pids...; waitfor=typemax(Int))
     cluster_mgmt_from_master_check()