Parse function docstrings into function schema parameter descriptions

[jackmpcollins]

Pop param descriptions from the docstring and put them as parameter descriptions in the function schema instead. Pydantic Field description should take preference if both are provided.

See discussion from PR #435

magentic does already support adding descriptions for function parameters. Functions are converted to pydantic models so pydantic's Field works for the params. See magentic.dev/function-calling#annotated-parameters

With this in mind, I would opt for making the docstring parsing part of create_model_from_function where it can add the param descriptions (and types?) from the docstring only if these were not specified using Field. With this in place, removing the params section from the docstring when covering it to the function description would make sense to keep a single source of truth for each param description.

https://github.com/mkdocstrings/griffe is an option maybe but requires paid plan to automatically detect docstring type 😓 https://mkdocstrings.github.io/griffe/guide/users/how-to/parse-docstrings/