From a29f9452b8f191e152c6606895f245ebb3eb203a Mon Sep 17 00:00:00 2001
From: jfh <jfh@imijmi.eu>
Date: Thu, 7 Oct 2021 14:12:47 +0300
Subject: [PATCH] Add documentation for Arg types.

---
 vm/src/function/numlike.rs | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/vm/src/function/numlike.rs b/vm/src/function/numlike.rs
index d6c528e1ab..27ec3625db 100644
--- a/vm/src/function/numlike.rs
+++ b/vm/src/function/numlike.rs
@@ -1,6 +1,15 @@
 use crate::{PyObjectRef, PyResult, TryFromObject, TypeProtocol, VirtualMachine};
 use num_complex::Complex64;
 
+/// A Python complex-like object.
+///
+/// `ArgComplexLike` implements `FromArgs` so that a built-in function can accept
+/// any object that can be transformed into a complex.
+///
+/// If the object is not a Python complex object but has a `__complex__()`
+/// method, this method will first be called to convert the object into a float.
+/// If `__complex__()` is not defined then it falls back to `__float__()`. If
+/// `__float__()` is not defined it falls back to `__index__()`.
 #[derive(Debug, Copy, Clone, PartialEq)]
 #[repr(transparent)]
 pub struct ArgComplexLike {
@@ -14,6 +23,7 @@ impl ArgComplexLike {
 }
 
 impl TryFromObject for ArgComplexLike {
+    // Equivalent to PyComplex_AsCComplex
     fn try_from_object(vm: &VirtualMachine, obj: PyObjectRef) -> PyResult<Self> {
         // We do not care if it was already a complex.
         let (value, _) = obj.try_complex(vm)?.ok_or_else(|| {
@@ -23,6 +33,14 @@ impl TryFromObject for ArgComplexLike {
     }
 }
 
+/// A Python float-like object.
+///
+/// `ArgFloatLike` implements `FromArgs` so that a built-in function can accept
+/// any object that can be transformed into a float.
+///
+/// If the object is not a Python floating point object but has a `__float__()`
+/// method, this method will first be called to convert the object into a float.
+/// If `__float__()` is not defined then it falls back to `__index__()`.
 #[derive(Debug, Copy, Clone, PartialEq)]
 #[repr(transparent)]
 pub struct ArgFloatLike {
@@ -44,6 +62,7 @@ impl ArgFloatLike {
 }
 
 impl TryFromObject for ArgFloatLike {
+    // Equivalent to PyFloat_AsDouble.
     fn try_from_object(vm: &VirtualMachine, obj: PyObjectRef) -> PyResult<Self> {
         let value = obj.try_to_f64(vm)?.ok_or_else(|| {
             vm.new_type_error(format!("must be real number, not {}", obj.class().name()))
@@ -52,6 +71,14 @@ impl TryFromObject for ArgFloatLike {
     }
 }
 
+/// A Python bool-like object.
+///
+/// `ArgBoolLike` implements `FromArgs` so that a built-in function can accept
+/// any object that can be transformed into a boolean.
+///
+/// By default an object is considered true unless its class defines either a
+/// `__bool__()` method that returns False or a `__len__()` method that returns
+/// zero, when called with the object.
 #[derive(Debug, Default, Copy, Clone, PartialEq)]
 pub struct ArgBoolLike {
     value: bool,