Document make_iterator/make_key_iterator

This adds brief API documentation for make_iterator/make_key_iterator,
specifically mentioning that it requires InputIterators.

Closes #734.

[skip ci] (no code change here)

include/pybind11/pybind11.h

@@ -1301,6 +1301,7 @@ NAMESPACE_END(detail)
 template <typename... Args> detail::init<Args...> init() { return detail::init<Args...>(); }
 template <typename... Args> detail::init_alias<Args...> init_alias() { return detail::init_alias<Args...>(); }
 
+/// Makes a python iterator from a first and past-the-end C++ InputIterator.
 template <return_value_policy Policy = return_value_policy::reference_internal,
           typename Iterator,
           typename Sentinel,
@@ -1326,6 +1327,8 @@ iterator make_iterator(Iterator first, Sentinel last, Extra &&... extra) {
     return (iterator) cast(state { first, last, true });
 }
 
+/// Makes an python iterator over the keys (`.first`) of a iterator over pairs from a
+/// first and past-the-end InputIterator.
 template <return_value_policy Policy = return_value_policy::reference_internal,
           typename Iterator,
           typename Sentinel,
@@ -1351,11 +1354,15 @@ iterator make_key_iterator(Iterator first, Sentinel last, Extra &&... extra) {
     return (iterator) cast(state { first, last, true });
 }
 
+/// Makes an iterator over values of an stl container or other container supporting
+/// `std::begin()`/`std::end()`
 template <return_value_policy Policy = return_value_policy::reference_internal,
           typename Type, typename... Extra> iterator make_iterator(Type &value, Extra&&... extra) {
     return make_iterator<Policy>(std::begin(value), std::end(value), extra...);
 }
 
+/// Makes an iterator over the keys (`.first`) of a stl map-like container supporting
+/// `std::begin()`/`std::end()`
 template <return_value_policy Policy = return_value_policy::reference_internal,
           typename Type, typename... Extra> iterator make_key_iterator(Type &value, Extra&&... extra) {
     return make_key_iterator<Policy>(std::begin(value), std::end(value), extra...);