Add documentation for call()/call_method().

CHANGELOG.md

@@ -10,6 +10,8 @@
 - [Added support for optional parameters][81] to `py_argparse!`, `py_fn!` and `py_class!` macros. (PR by [@Luthaf])
 
   Example: `py_fn!(py, function(i: i32 = 0))`
+- Made `ObjectProtocol::compare()` available on Python 3.
+- Added `ObjectProtocol::rich_compare()`.
 
 [Unreleased]: https://github.com/dgrunwald/rust-cpython/compare/0.1.0...HEAD
 [81]: https://github.com/dgrunwald/rust-cpython/pull/81

README.md

@@ -8,7 +8,7 @@ rust-cpython [![Build Status](https://travis-ci.org/dgrunwald/rust-cpython.svg?b
 
 ---
 
-Copyright (c) 2015-2016 Daniel Grunwald.
+Copyright (c) 2015-2017 Daniel Grunwald.
 Rust-cpython is licensed under the [MIT license](http://opensource.org/licenses/MIT).
 Python is licensed under the [Python License](https://docs.python.org/2/license.html).
 
@@ -18,7 +18,7 @@ Supported Python versions:
 
 Supported Rust version:
 * Rust 1.13.0 or later
-* On Windows, we require rustc 1.15.0-nightly
+* On Windows, Rust 1.15.0 or later
 
 # Usage
 

src/objectprotocol.rs

@@ -180,6 +180,11 @@ pub trait ObjectProtocol : PythonObject {
 
     /// Calls the object.
     /// This is equivalent to the Python expression: 'self(*args, **kwargs)'
+    ///
+    /// `args` should be a value that, when converted to Python, results in a tuple.
+    /// For this purpose, you can use:
+    ///  * `cpython::NoArgs` when calling a method without any arguments
+    ///  * otherwise, a Rust tuple with 1 or more elements
     #[inline]
     fn call<A>(&self, py: Python, args: A, kwargs: Option<&PyDict>) -> PyResult<PyObject>
         where A: ToPyObject<ObjectType=PyTuple>
@@ -191,6 +196,24 @@ pub trait ObjectProtocol : PythonObject {
 
     /// Calls a method on the object.
     /// This is equivalent to the Python expression: 'self.name(*args, **kwargs)'
+    ///
+    /// `args` should be a value that, when converted to Python, results in a tuple.
+    /// For this purpose, you can use:
+    ///  * `cpython::NoArgs` when calling a method without any arguments
+    ///  * otherwise, a Rust tuple with 1 or more elements
+    ///
+    /// # Example
+    /// ```no_run
+    /// use cpython::{NoArgs, ObjectProtocol};
+    /// # use cpython::Python;
+    /// # let gil = Python::acquire_gil();
+    /// # let py = gil.python();
+    /// # let obj = py.None();
+    /// // Call method without arguments:
+    /// let value = obj.call_method(py, "method0", NoArgs, None).unwrap();
+    /// // Call method with a single argument:
+    /// obj.call_method(py, "method1", (true,), None).unwrap();
+    /// ```
     #[inline]
     fn call_method<A>(&self, py: Python, name: &str, args: A, kwargs: Option<&PyDict>) -> PyResult<PyObject>
         where A: ToPyObject<ObjectType=PyTuple>

src/objects/module.rs

@@ -92,6 +92,24 @@ impl PyModule {
 
     /// Calls a function in the module.
     /// This is equivalent to the Python expression: `getattr(module, name)(*args, **kwargs)`
+    ///
+    /// `args` should be a value that, when converted to Python, results in a tuple.
+    /// For this purpose, you can use:
+    ///  * `cpython::NoArgs` when calling a method without any arguments
+    ///  * otherwise, a Rust tuple with 1 or more elements
+    ///
+    /// # Example
+    /// ```
+    /// use cpython::NoArgs;
+    /// # use cpython::Python;
+    /// # let gil = Python::acquire_gil();
+    /// # let py = gil.python();
+    /// let sys = py.import("sys").unwrap();
+    /// // Call function without arguments:
+    /// let encoding = sys.call(py, "getdefaultencoding", NoArgs, None).unwrap();
+    /// // Call function with a single argument:
+    /// sys.call(py, "setrecursionlimit", (1000,), None).unwrap();
+    /// ```
     pub fn call<A>(&self, py: Python, name: &str, args: A, kwargs: Option<&PyDict>) -> PyResult<PyObject>
         where A: ToPyObject<ObjectType=PyTuple>
     {