clarify the docs of isolation (#17335)

* improve test coverage for isolation

* a bit better

* clarify the docs of isolation

1 files changed, 7 insertions, 1 deletions

diff --git a/lib/std/isolation.nim b/lib/std/isolation.nim
index 94abef807..8daca233b 100644
--- a/lib/std/isolation.nim
+++ b/lib/std/isolation.nim
@@ -29,15 +29,21 @@ proc `=destroy`*[T](dest: var Isolated[T]) {.inline.} =
   `=destroy`(dest.value)
 
 func isolate*[T](value: sink T): Isolated[T] {.magic: "Isolate".} =
-  ## Create an isolated subgraph from the expression `value`.
+  ## Creates an isolated subgraph from the expression `value`.
+  ## Isolation is checked at compile time.
+  ##
   ## Please read https://github.com/nim-lang/RFCs/issues/244
   ## for more details.
   Isolated[T](value: value)
 
 func unsafeIsolate*[T](value: sink T): Isolated[T] =
   ## Creates an isolated subgraph from the expression `value`.
+  ## 
+  ## .. warning:: The proc doesn't check whether `value` is isolated.
+  ## 
   Isolated[T](value: value)
 
 func extract*[T](src: var Isolated[T]): T =
   ## Returns the internal value of `src`.
+  ## The value is moved from `src`.
   result = move(src.value)