From f88af0c127c39c6025e75eb8ee482bf752cdca3a Mon Sep 17 00:00:00 2001
From: Wenzel Jakob <wenzel.jakob@epfl.ch>
Date: Wed, 22 Jun 2016 13:52:31 +0200
Subject: [PATCH] clarification on static properties (fixes #248)

---
 docs/advanced.rst  | 20 ++++++++++++++++++++
 docs/changelog.rst |  4 ++--
 docs/classes.rst   |  5 ++++-
 3 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/docs/advanced.rst b/docs/advanced.rst
index 00e43f972..6138af888 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -607,6 +607,26 @@ Python side:
 
     py::implicitly_convertible<A, B>();
 
+.. _static_properties:
+
+Static properties
+=================
+
+The section on :ref:`properties` discussed the creation of instance properties
+that are implemented in terms of C++ getters and setters.
+
+Static properties can also be created in a similar way to expose getters and
+setters of static class attributes. It is important to note that the implicit
+``self`` argument also exists in this case and is used to pass the Python
+``type`` subclass instance. This parameter will often not be needed by the C++
+side, and the following example illustrates how to instantiate a lambda getter
+function that ignores it:
+
+.. code-block:: cpp
+
+    py::class_<Foo>(m, "Foo")
+        .def_property_readonly_static("foo", [](py::object /* self */) { return Foo(); });
+
 Unique pointers
 ===============
 
diff --git a/docs/changelog.rst b/docs/changelog.rst
index ffae32b5d..6560072a6 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -7,14 +7,14 @@ Starting with version 1.8, pybind11 releases use a
 [semantic versioning](http://semver.org) policy.
 
 Breaking changes queued for v2.0.0 (Not yet released)
----------------------------------------------------
+-----------------------------------------------------
 * Redesigned virtual call mechanism and user-facing syntax (see
   https://github.com/pybind/pybind11/commit/86d825f3302701d81414ddd3d38bcd09433076bc)
 
 * Remove ``handle.call()`` method
 
 1.9.0 (Not yet released)
-----------------------
+------------------------
 * Queued changes: ``py::eval*``, map indexing suite, documentation for indexing suites.
 
 1.8.0 (June 14, 2016)
diff --git a/docs/classes.rst b/docs/classes.rst
index a3a0bf387..5afb21edc 100644
--- a/docs/classes.rst
+++ b/docs/classes.rst
@@ -104,6 +104,8 @@ With the above change, the same Python code now produces the following output:
     >>> print(p)
     <example.Pet named 'Molly'>
 
+.. _properties:
+
 Instance and static fields
 ==========================
 
@@ -160,7 +162,8 @@ the setter and getter functions:
     Similar functions :func:`class_::def_readwrite_static`,
     :func:`class_::def_readonly_static` :func:`class_::def_property_static`,
     and :func:`class_::def_property_readonly_static` are provided for binding
-    static variables and properties.
+    static variables and properties. Please also see the section on
+    :ref:`static_properties` in the advanced part of the documentation.
 
 .. _inheritance: