stronger warnings about changing constants in help and docs

base/docs/basedocs.jl

@@ -260,7 +260,7 @@ kw"'"
 """
     const
 
-`const` is used to declare global variables which are also constant. In almost all code
+`const` is used to declare global variables whose values will not change. In almost all code
 (and particularly performance sensitive code) global variables should be declared
 constant in this way.
 
@@ -275,15 +275,17 @@ const y, z = 7, 11
 
 Note that `const` only applies to one `=` operation, therefore `const x = y = 1`
 declares `x` to be constant but not `y`. On the other hand, `const x = const y = 1`
-declares both `x` and `y` as constants.
+declares both `x` and `y` constant.
 
-Note that "constant-ness" is not enforced inside containers, so if `x` is an array or
-dictionary (for example) you can still add and remove elements.
+Note that "constant-ness" does not extend into mutable containers; only the
+association between a variable and its value is constant.
+If `x` is an array or dictionary (for example) you can still modify, add, or remove elements.
 
-Technically, you can even redefine `const` variables, although this will generate a
-warning from the compiler. The only strict requirement is that the *type* of the
-variable does not change, which is why `const` variables are much faster than regular
-globals.
+In some cases changing the value of a `const` variable gives a warning instead of
+an error.
+However, this can produce unpredictable behavior or corrupt the state of your program,
+and so should be avoided.
+This feature is intended only for convenience during interactive use.
 """
 kw"const"
 

doc/src/manual/variables-and-scoping.md

@@ -522,7 +522,7 @@ julia> const z = 100
 julia> z = 100
 100
 ```
-The last rule applies for immutable objects even if the vairable binding would change, e.g.:
+The last rule applies for immutable objects even if the variable binding would change, e.g.:
 ```julia-repl
 julia> const s1 = "1"
 "1"
@@ -555,8 +555,11 @@ WARNING: redefining constant a
  1
 ```
 
-Note that although possible, changing the value of a variable that is declared as constant
-is strongly discouraged. For instance, if a method references a constant and is already
+Note that although sometimes possible, changing the value of a `const` variable
+is strongly discouraged, and is intended only for convenience during
+interactive use.
+Changing constants can cause various problems or unexpected behaviors.
+For instance, if a method references a constant and is already
 compiled before the constant is changed then it might keep using the old value:
 ```jldoctest
 julia> const x = 1