diff --git a/base/osutils.jl b/base/osutils.jl
index 95d0562540e5a..bd6cdf086bfd0 100644
--- a/base/osutils.jl
+++ b/base/osutils.jl
@@ -3,13 +3,23 @@
 """
     @static
 
-Partially evaluate an expression at parse time.
+Partially evaluate an expression at macro expansion time.
 
-For example, `@static Sys.iswindows() ? foo : bar` will evaluate `Sys.iswindows()` and insert
-either `foo` or `bar` into the expression.
-This is useful in cases where a construct would be invalid on other platforms,
-such as a `ccall` to a non-existent function.
-`@static if Sys.isapple() foo end` and `@static foo <&&,||> bar` are also valid syntax.
+This is useful in cases where a construct would be invalid in some cases, such as a `ccall`
+to a os-dependent function, or macros defined in packages that are not imported.
+
+`@static` requires a conditional. The conditional can be in an `if` statement, a ternary
+operator, or `&&`\`||`. The conditional is evaluated by recursively expanding macros,
+lowering and executing the resulting expressions. Then, the matching branch (if any) is
+returned. All the other branches of the conditional are deleted before they are
+macro-expanded (and lowered or executed).
+
+# Example
+
+Suppose we want to parse an expression `expr` that is valid only on MacOS. We could solve
+this problem using `@static` with `@static if Sys.isapple() expr end`. In case we had
+`expr_apple` for MacOS and `expr_others` for the other operating systems, the solution with
+`@static` would be `@static Sys.isapple() ? expr_apple : expr_others`.
 """
 macro static(ex)
     if isa(ex, Expr)