From ba8e3bbb3a69564015dd33e85878d90360a16114 Mon Sep 17 00:00:00 2001
From: Fengyang Wang <fengyang.wang.0@gmail.com>
Date: Wed, 26 Apr 2017 13:07:02 -0400
Subject: [PATCH] Fix #16742, document Iterators.filter (#21550)

---
 base/iterators.jl | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/base/iterators.jl b/base/iterators.jl
index 230909f4984c0..e193a865c62ae 100644
--- a/base/iterators.jl
+++ b/base/iterators.jl
@@ -247,6 +247,21 @@ struct Filter{F,I}
     itr::I
 end
 
+"""
+    Iterators.filter(flt, itr)
+
+Given a predicate function `flt` and an iterable object `itr`, return an
+iterable object which upon iteration yields the elements `x` of `itr` that
+satisfy `flt(x)`. The order of the original iterator is preserved.
+
+This function is *lazy*; that is, it is guaranteed to return in ``Θ(1)`` time
+and use ``Θ(1)`` additional space, and `flt` will not be called by an
+invocation of `filter`. Calls to `flt` will be made when iterating over the
+returned iterable object. These calls are not cached and repeated calls will be
+made when reiterating.
+
+See [`Base.filter`](@ref) for an eager implementation of filtering for arrays.
+"""
 filter(flt, itr) = Filter(flt, itr)
 
 start(f::Filter) = start_filter(f.flt, f.itr)