From 32e0d3560395fef9a16d01d7b61d6fdfa589c538 Mon Sep 17 00:00:00 2001
From: Daniel Grunwald <daniel@danielgrunwald.de>
Date: Fri, 27 Jan 2017 21:51:56 +0100
Subject: [PATCH] Update documentation

---
 src/argparse.rs |  8 ++++++++
 src/err.rs      | 33 ++++++++++++++++++---------------
 2 files changed, 26 insertions(+), 15 deletions(-)

diff --git a/src/argparse.rs b/src/argparse.rs
index 8e64a697..49caf2e3 100644
--- a/src/argparse.rs
+++ b/src/argparse.rs
@@ -120,6 +120,7 @@ pub fn parse_args(
 ///    5. `*name : ty`
 ///    6. `**name`
 ///    7. `**name : ty`
+///
 ///   The types used must implement the `FromPyObject` trait.
 ///   If no type is specified, the parameter implicitly uses
 ///   `&PyObject` (format 1), `&PyTuple` (format 4) or `&PyDict` (format 6).
@@ -132,6 +133,13 @@ pub fn parse_args(
 /// them to the parameters. If the extraction is successful, `py_argparse!()` evaluates
 /// the body expression and returns of that evaluation.
 /// If extraction fails, `py_argparse!()` returns a failed `PyResult` without evaluating `body`.
+///
+/// The `py_argparse!()` macro special-cases reference types (when `ty` starts with a `&` token):
+/// In this case, the macro uses the `RefFromPyObject` trait instead of the `FromPyObject` trait.
+/// When using at least one reference parameter, the `body` block is placed within a closure,
+/// so `return` statements might behave unexpectedly in this case. (this only affects direct use
+/// of `py_argparse!`; `py_fn!` is unaffected as the body there is always in a separate function
+/// from the generated argument-parsing code).
 #[macro_export]
 macro_rules! py_argparse {
     ($py:expr, $fname:expr, $args:expr, $kwargs:expr, $plist:tt $body:block) => {
diff --git a/src/err.rs b/src/err.rs
index f46e748d..6c168e95 100644
--- a/src/err.rs
+++ b/src/err.rs
@@ -141,6 +141,23 @@ pub struct PyErr {
 pub type PyResult<T> = Result<T, PyErr>;
 
 impl PyErr {
+    /// Creates a new PyErr of type `T`.
+    ///
+    /// `value` can be:
+    /// * `NoArgs`: the exception instance will be created using python `T()`
+    /// * a tuple: the exception instance will be created using python `T(*tuple)`
+    /// * any other value: the exception instance will be created using python `T(value)`
+    ///
+    /// Panics if `T` is not a python class derived from `BaseException`.
+    ///
+    /// Example:
+    ///  `return Err(PyErr::new::<exc::TypeError, _>(py, "Error message"));`
+    pub fn new<T, V>(py: Python, value: V) -> PyErr
+        where T: PythonObjectWithTypeObject, V: ToPyObject
+    {
+        PyErr::new_helper(py, py.get_type::<T>(), value.to_py_object(py).into_object())
+    }
+
     /// Gets whether an error is present in the Python interpreter's global state.
     #[inline]
     pub fn occurred(_ : Python) -> bool {
@@ -199,20 +216,6 @@ impl PyErr {
         }
     }
 
-    /// Creates a new PyErr of type `T`.
-    ///
-    /// `value` can be:
-    /// * `NoArgs`: the exception instance will be created using python `T()`
-    /// * a tuple: the exception instance will be created using python `T(*tuple)`
-    /// * any other value: the exception instance will be created using python `T(value)`
-    ///
-    /// Panics if `T` is not a python class derived from `BaseException`.
-    pub fn new<T, V>(py: Python, value: V) -> PyErr
-        where T: PythonObjectWithTypeObject, V: ToPyObject
-    {
-        PyErr::new_helper(py, py.get_type::<T>(), value.to_py_object(py).into_object())
-    }
-
     fn new_helper(_py: Python, ty: PyType, value: PyObject) -> PyErr {
         assert!(unsafe { ffi::PyExceptionClass_Check(ty.as_object().as_ptr()) } != 0);
         PyErr {
@@ -254,7 +257,7 @@ impl PyErr {
     }
 
     /// Construct a new error, with the usual lazy initialization of Python exceptions.
-    /// `exc` is the exception type; usually one of the standard exceptions like `PyExc::runtime_error()`.
+    /// `exc` is the exception type; usually one of the standard exceptions like `py.get_type::<exc::RuntimeError>()`.
     /// `value` is the exception instance, or a tuple of arguments to pass to the exception constructor.
     #[inline]
     pub fn new_lazy_init(exc: PyType, value: Option<PyObject>) -> PyErr {