document local methods, warn about branches

doc/src/manual/methods.md

@@ -1105,4 +1105,44 @@ reduced likelihood of ambiguities. Moreover, it extends the "public"
 `myfilter` interface: a user who wants to control the padding
 explicitly can call the `NoPad` variant directly.
 
+## Defining methods in local scope
+
+You can define methods within a [local scope](@ref scope-of-variables), for example
+
+```jldoctest
+julia> function f(x)
+ g(y::Int) = y + x
+ g(y) = y - x
+ g
+ end
+f (generic function with 1 method)
+
+julia> h = f(3)
+(::var"#g#6"{Int64}) (generic function with 2 methods)
+
+julia> h(4)
+7
+
+julia> h(4.0)
+1.0
+```
+
+However, you should *not* define local methods conditionally or subject to control flow, as in
+```julia
+function f2(inc)
+ if inc
+ g(x) = x + 1
+ else
+ g(x) = x - 1
+ end
+end
+
+function f3()
+ function g end
+ return g
+ g() = 0
+end
+```
+as this leads to undefined behavior.
+
 [^Clarke61]: Arthur C. Clarke, *Profiles of the Future* (1961): Clarke's Third Law.