Add docs

mooreryan · mooreryan · commit cd25bb898196 · 2022-02-08T19:32:19.000-05:00
diff --git a/_docs_src/mkdocs.yml b/_docs_src/mkdocs.yml
@@ -22,6 +22,7 @@ nav:
     - Class & Static Methods; Functions: static-methods.md
   - Miscellaneous:
     - Auto-generating bindings: auto-gen-bindings.md
+    - Attributes -- py_fun_name: py_fun_name.md
     - CLI Options: cli-options.md
     - Converting `pyobjects` to OCaml types: of-pyobject.md
     - Embedding Python source: embedding-python.md
diff --git a/_docs_src/src/py_fun_name.md b/_docs_src/src/py_fun_name.md
@@ -0,0 +1,37 @@
+# Attributes
+
+You can attach certain attributes to your value specifications to change their behavior.
+
+Currently, the only recognized attribute is `py_fun_name`.
+
+You can use it to bind a Python method to a differently named OCaml function.
+
+## Example
+
+For example, rather than having a `Cat.__init__` method to call from the OCaml side (i.e., to make a new Python `Cat` object), you can bind the Python `__init__` function to something more idiomatic like `create` or whatever you want.
+
+```ocaml
+val create : t -> ...
+[@@py_fun_name __init__]
+```
+
+Another common use for this is to bind the Python `__str__` method for a class to `to_string` on the OCaml side.
+
+You can do this with any function.  One reason is that you may want to have some type safety with a polymorphic Python function.  While you could pass in [Py.Object.t](https://mooreryan.github.io/ocaml_python_bindgen/types/#pytypes) directly, you could also use attributes to bind multiple OCaml functions to the same Python method.  E.g.,
+
+```ocaml
+val eat : t -> num_mice:int -> unit -> unit
+
+val eat_part : t -> num_mice:float -> unit -> unit
+[@@py_fun_name eat]
+```
+
+In this case, we have one `eat` function for `int` and one for `float`.
+
+## Full example
+
+For a full working example see the [attributes](https://github.com/mooreryan/ocaml_python_bindgen/tree/main/examples/attributes) example on GitHub.
+
+## Warning
+
+If you specify the `py_fun_name` more than once, it will do something wonky.  Eventually, the program will treat this as an error, but for now, it is on you to avoid doing it.
