From 3d591e8f2f6d06176884f33cd271bdd3d65294b4 Mon Sep 17 00:00:00 2001
From: Jason Rhinelander <jason@imaginary.ca>
Date: Sat, 18 Mar 2017 13:34:21 -0300
Subject: [PATCH] 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 | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/include/pybind11/pybind11.h b/include/pybind11/pybind11.h
index e90c69aee..9c7c11b46 100644
--- a/include/pybind11/pybind11.h
+++ b/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...);