clarification on static properties (fixes #248)

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
 ===============
 

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)

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: