document arg + return value modifiers

Author: brettmc

phper-doc/doc/_06_module/_02_register_functions/index.md

@@ -80,3 +80,43 @@ pub fn get_module() -> Module {
 Here, the argument is registered as
 [`Argument::by_ref`](phper::functions::Argument::by_ref).  Therefore, the type of
 the `count` parameter is no longer long, but a reference.
+
+## Argument and return type modifiers
+
+Arguments can have type-hints, nullability and default values applied. Here we define a function that accepts
+a nullable class (in this case, an interface), and a string with a default value:
+
+```rust,no-run
+use phper::{modules::Module, php_get_module, functions::Argument, echo};
+
+#[php_get_module]
+pub fn get_module() -> Module {
+    let mut module = Module::new(
+        env!("CARGO_CRATE_NAME"),
+        env!("CARGO_PKG_VERSION"),
+        env!("CARGO_PKG_AUTHORS"),
+    );
+
+    module.add_function("my_function", |_| -> phper::Result<()> {
+        Ok(())
+    })
+    .argument(Argument::by_val("a_class").with_type_hint(ArgumentTypeHint::ClassEntry(String::from(r"\MyNamespace\MyInterface"))).allow_null())
+    .argument(Argument::by_val("name").with_type_hint(ArgumentTypeHint::String).with_default_value(CString::new("'my_default'").unwrap()))
+    .argument(Argument::by_val("optional_bool").with_type_hint(ArgumentTypeHint::Bool).optional());
+
+    module
+}
+```
+
+The output of `php --re` for this function would look like:
+
+```txt
+    Function [ <internal:integration> function my_function ] {
+
+      - Parameters [3] {
+        Parameter #0 [ <required> ?class_name $a_class ]
+        Parameter #1 [ <optional> string $name = 'my_default' ]
+        Parameter #2 [ <optional> bool $optional_bool = <default> ]
+      }
+    }
+```

phper-doc/doc/_06_module/_06_register_class/index.md

@@ -102,6 +102,28 @@ foo.add_static_method(
 ).argument(Argument::by_val("name"));
 ```
 
+## Argument and return type modifiers
+
+Methods may add argument and return typehints as per functions. For example:
+
+```rust,no-run
+use phper::classes::{ClassEntity, ClassEntry, Visibility};
+use phper::functions::Argument;
+use phper::types::{ArgumentTypeHint, ReturnTypeHint},
+
+let mut foo = ClassEntity::new("Foo");
+foo.add_method(
+    "test",
+    Visibility::Public,
+    |_this, _arguments| {
+        Ok(())
+    },
+)
+.argument(Argument::by_val("a_string").with_type_hint(ArgumentTypeHint::String))
+.argument(Argument::by_val("an_interface").with_type_hint(ArgumentTypeHint::ClassEntry(String::from(r"\MyNamespace\MyInterface")))))
+.return_type(ReturnType::by_val(ReturnTypeHint::Bool).allow_null());
+```
+
 ## Add constants
 Interfaces can have public constants. Value can be string|int|bool|float|null.
 

phper/src/functions.rs

@@ -540,10 +540,10 @@ impl Argument {
         self
     }
 
-    /// Argument default value (always a String)
+    /// Argument default value. Example: "'a-string'", "A_CONST", "42", "[0=>'zero']"
     pub fn with_default_value(mut self, default_value: CString) -> Self {
         self.default_value = Some(default_value);
-        self.required = false; // important!
+        self.required = false; // arg with default value does not count towards required arg count
         self
     }
 }