@@ -45,7 +45,17 @@ The PyRef type implements
4545https://doc.rust-lang.org/std/cell/index.html#introducing-mutability-inside-of-something-immutable
4646*/
4747pub type PyRef < T > =Rc < RefCell < T > > ;
48+
49+ /// The `PyObjectRef` is one of the most used types. It is a reference to a
50+ /// python object. A single python object can have multiple references, and
51+ /// this reference counting is accounted for by this type. Use the `.clone()`
52+ /// method to create a new reference and increment the amount of references
53+ /// to the python object by 1.
4854pub type PyObjectRef =PyRef < PyObject > ;
55+
56+ /// Use this type for function which return a python object or and exception.
57+ /// Both the python object and the python exception are `PyObjectRef` types
58+ /// since exceptions are also python objects.
4959pub type PyResult =Result < PyObjectRef , PyObjectRef > ; // A valid value, or an exception
5060
5161/*
@@ -407,6 +417,9 @@ impl PyContext {
407417}
408418}
409419
420+ /// This is an actual python object. It consists of a `typ` which is the
421+ /// python class, and carries some rust payload optionally. This rust
422+ /// payload can be a rust float or rust int in case of float and int objects.
410423pub struct PyObject {
411424pub kind : PyObjectKind ,
412425pub typ : Option < PyObjectRef > ,
@@ -594,6 +607,9 @@ impl fmt::Debug for PyObject {
594607}
595608}
596609
610+ /// The `PyFuncArgs` struct is one of the most used structs then creating
611+ /// a rust function that can be called from python. It holds both positional
612+ /// arguments, as well as keyword arguments passed to the function.
597613#[ derive( Debug , Default , Clone ) ]
598614pub struct PyFuncArgs {
599615pub args : Vec < PyObjectRef > ,
@@ -637,6 +653,10 @@ impl PyFuncArgs {
637653
638654type RustPyFunc =fn ( vm : & mut VirtualMachine , PyFuncArgs ) ->PyResult ;
639655
656+ /// Rather than determining the type of a python object, this enum is more
657+ /// a holder for the rust payload of a python object. It is more a carrier
658+ /// of rust data for a particular python object. Determine the python type
659+ /// by using for example the `.typ()` method on a python object.
640660pub enum PyObjectKind {
641661String {
642662value : String ,