document complexity of push!

Author: stevengj

base/docs/helpdb/Base.jl

@@ -1406,6 +1406,10 @@ julia> push!([1, 2, 3], 4, 5, 6)
  6
 ```
 
+Internally, the storage for the array is increased exponentially (by 50%)
+as needed, so that calling `push!` ``n`` times on an empty array
+involves only ``O(\log n)`` allocations and ``O(n)`` time.
+
 Use [`append!`](:func:`append!`) to add all the elements of another collection to
 `collection`. The result of the preceding example is equivalent to `append!([1, 2, 3], [4,
 5, 6])`.

doc/stdlib/collections.rst

@@ -1022,6 +1022,8 @@ Dequeues
         5
         6
 
+   Internally, the storage for the array is increased exponentially (by 50%) as needed, so that calling ``push!`` :math:`n` times on an empty array involves only :math:`O(log n)` allocations and :math:`O(n)` time.
+
    Use :func:`append!` to add all the elements of another collection to ``collection``\ . The result of the preceding example is equivalent to ``append!([1, 2, 3], [4, 5, 6])``\ .
 
 .. function:: pop!(collection) -> item
@@ -1385,4 +1387,3 @@ is used, so that elements popped from the heap are given in ascending order.
    .. Docstring generated from Julia source
 
    Given a binary heap-ordered array, remove and return the lowest ordered element. For efficiency, this function does not check that the array is indeed heap-ordered.
-